taski 0.5.0 → 0.7.0

data/examples/{context_demo.rb → args_demo.rb}

@@ -1,36 +1,36 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Taski Context API Example
+# Taski Args API Example
 #
-# This example demonstrates the Context API for accessing runtime information:
+# This example demonstrates the Args API for accessing runtime information:
 # - working_directory: Where execution started
 # - started_at: When execution began
 # - root_task: The first task class that was called
-# - User-defined options: Custom values passed via run(context: {...})
+# - User-defined options: Custom values passed via run(args: {...})
 #
-# Run: ruby examples/context_demo.rb
+# Run: ruby examples/args_demo.rb
 
 require_relative "../lib/taski"
 
-puts "Taski Context API Example"
+puts "Taski Args API Example"
 puts "=" * 40
 
-# Task that uses context information for logging
+# Task that uses args information for logging
 class SetupTask < Taski::Task
   exports :setup_info
 
   def run
     puts "Setup running..."
-    puts "  Working directory: #{Taski.context.working_directory}"
-    puts "  Started at: #{Taski.context.started_at}"
-    puts "  Root task: #{Taski.context.root_task}"
-    puts "  Environment: #{Taski.context[:env]}"
+    puts "  Working directory: #{Taski.args.working_directory}"
+    puts "  Started at: #{Taski.args.started_at}"
+    puts "  Root task: #{Taski.args.root_task}"
+    puts "  Environment: #{Taski.args[:env]}"
 
     @setup_info = {
-      directory: Taski.context.working_directory,
-      timestamp: Taski.context.started_at,
-      env: Taski.context[:env]
+      directory: Taski.args.working_directory,
+      timestamp: Taski.args.started_at,
+      env: Taski.args[:env]
     }
   end
 end
@@ -40,9 +40,9 @@ class FileProcessor < Taski::Task
   exports :output_path
 
   def run
-    # Use context to determine output location
-    base_dir = Taski.context.working_directory
-    env = Taski.context.fetch(:env, "development")
+    # Use args to determine output location
+    base_dir = Taski.args.working_directory
+    env = Taski.args.fetch(:env, "development")
     @output_path = File.join(base_dir, "tmp", env, "output.txt")
 
     puts "FileProcessor: Would write to #{@output_path}"
@@ -55,12 +55,12 @@ class TimingTask < Taski::Task
   exports :duration_info
 
   def run
-    start_time = Taski.context.started_at
+    start_time = Taski.args.started_at
     current_time = Time.now
     elapsed = current_time - start_time
 
     puts "TimingTask: #{elapsed.round(3)}s since execution started"
-    puts "  Debug mode: #{Taski.context.fetch(:debug, false)}"
+    puts "  Debug mode: #{Taski.args.fetch(:debug, false)}"
 
     @duration_info = {
       started: start_time,
@@ -76,8 +76,8 @@ class MainTask < Taski::Task
 
   def run
     puts "\nMainTask executing..."
-    puts "  Root task is: #{Taski.context.root_task}"
-    puts "  Environment: #{Taski.context[:env]}"
+    puts "  Root task is: #{Taski.args.root_task}"
+    puts "  Environment: #{Taski.args[:env]}"
 
     # Access dependencies
     setup = SetupTask.setup_info
@@ -88,7 +88,7 @@ class MainTask < Taski::Task
       setup: setup,
       output_path: output,
       timing: timing,
-      root_task: Taski.context.root_task.to_s
+      root_task: Taski.args.root_task.to_s
     }
 
     puts "\nExecution Summary:"
@@ -98,15 +98,15 @@ class MainTask < Taski::Task
   end
 end
 
-puts "\n1. Running MainTask with context options"
+puts "\n1. Running MainTask with args options"
 puts "-" * 40
-MainTask.run(context: {env: "production", debug: true})
+MainTask.run(args: {env: "production", debug: true})
 
 puts "\n" + "=" * 40
-puts "\n2. Running SetupTask directly with different context"
+puts "\n2. Running SetupTask directly with different args"
 puts "-" * 40
 SetupTask.reset!
-SetupTask.run(context: {env: "staging"})
+SetupTask.run(args: {env: "staging"})
 
 puts "\n" + "=" * 40
 puts "\n3. Dependency Tree"
@@ -114,5 +114,5 @@ puts "-" * 40
 puts MainTask.tree
 
 puts "\n" + "=" * 40
-puts "Context API demonstration complete!"
-puts "Note: Context provides runtime information and user options without affecting dependency analysis."
+puts "Args API demonstration complete!"
+puts "Note: Args provides runtime information and user options without affecting dependency analysis."

data/examples/clean_demo.rb

@@ -0,0 +1,204 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Clean Demo
+#
+# This example demonstrates the clean functionality:
+# - Defining clean methods for resource cleanup
+# - Reverse dependency order execution (dependents cleaned before dependencies)
+# - Parallel clean execution when possible
+#
+# Run: ruby examples/clean_demo.rb
+
+require_relative "../lib/taski"
+
+puts "Taski Clean Demo"
+puts "=" * 40
+
+# Simulated build artifact paths
+BUILD_DIR = "/tmp/taski_clean_demo"
+
+# Base task: creates a build directory
+class SetupBuildDir < Taski::Task
+  exports :build_path
+
+  ##
+  # Prepares the task's build directory and simulates its creation.
+  #
+  # Sets the task's exported `build_path` to the "build" subdirectory under `BUILD_DIR`
+  # and performs a simulated creation step with informational output.
+  def run
+    @build_path = "#{BUILD_DIR}/build"
+    puts "[SetupBuildDir] Creating build directory: #{@build_path}"
+    # Simulated directory creation
+    sleep 0.8
+  end
+
+  ##
+  # Removes the directory referenced by @build_path.
+  # Cleans up build artifacts created by this task.
+  def clean
+    puts "[SetupBuildDir] Removing build directory: #{@build_path}"
+    # Simulated directory removal
+    sleep 0.8
+  end
+end
+
+# Compiles source code (depends on build directory)
+class CompileSource < Taski::Task
+  exports :binary_path
+
+  ##
+  # Compiles source artifacts and sets the compiled binary path for downstream tasks.
+  # This method sets @binary_path to the build directory's "app.bin" file and emits a console message indicating the compilation target.
+  def run
+    build_dir = SetupBuildDir.build_path
+    @binary_path = "#{build_dir}/app.bin"
+    puts "[CompileSource] Compiling to: #{@binary_path}"
+    sleep 1.5
+  end
+
+  ##
+  # Removes the compiled binary produced by this task.
+  # Performs the task's cleanup step and simulates the deletion process.
+  def clean
+    puts "[CompileSource] Removing compiled binary: #{@binary_path}"
+    sleep 0.6
+  end
+end
+
+# Generates documentation (depends on build directory)
+class GenerateDocs < Taski::Task
+  exports :docs_path
+
+  ##
+  # Generates documentation for the build and records the output path.
+  #
+  # Sets the task's `@docs_path` to the "docs" subdirectory under `SetupBuildDir.build_path`
+  # and prints a progress message to STDOUT.
+  def run
+    build_dir = SetupBuildDir.build_path
+    @docs_path = "#{build_dir}/docs"
+    puts "[GenerateDocs] Generating docs to: #{@docs_path}"
+    sleep 1.2
+  end
+
+  ##
+  # Removes the generated documentation at the task's docs_path.
+  # Prints a removal message for @docs_path and simulates its deletion.
+  def clean
+    puts "[GenerateDocs] Removing generated docs: #{@docs_path}"
+    sleep 0.5
+  end
+end
+
+# Creates release package (depends on both compiled source and docs)
+class CreateRelease < Taski::Task
+  exports :release_path
+
+  ##
+  # Creates the release package path and announces the included artifacts.
+  # Uses CompileSource.binary_path and GenerateDocs.docs_path to determine the package inputs, sets @release_path to "#{BUILD_DIR}/release.zip", and prints the binary, docs, and output paths.
+  def run
+    binary = CompileSource.binary_path
+    docs = GenerateDocs.docs_path
+    @release_path = "#{BUILD_DIR}/release.zip"
+    puts "[CreateRelease] Creating release package with:"
+    puts "  - Binary: #{binary}"
+    puts "  - Docs: #{docs}"
+    puts "  - Output: #{@release_path}"
+    sleep 0.7
+  end
+
+  ##
+  # Removes the release package produced by this task.
+  # Uses the task's `@release_path` as the target for cleanup.
+  def clean
+    puts "[CreateRelease] Removing release package: #{@release_path}"
+    sleep 0.5
+  end
+end
+
+puts "\n--- Task Tree Structure ---"
+puts CreateRelease.tree
+puts
+
+puts "--- Running build process ---"
+CreateRelease.run
+puts
+
+puts "Build completed!"
+puts "  Release: #{CreateRelease.release_path}"
+puts
+
+puts "--- Cleaning up (reverse dependency order) ---"
+puts "Note: CreateRelease cleans first, then CompileSource/GenerateDocs in parallel,"
+puts "      and finally SetupBuildDir cleans last."
+puts
+
+# Reset to allow clean execution
+Taski::Task.reset!
+
+# Re-run to set up state for clean
+CreateRelease.run
+
+puts "\nNow cleaning..."
+CreateRelease.clean
+
+puts
+puts "Clean completed! All artifacts removed."
+
+puts
+puts "=" * 40
+puts "run_and_clean Demo"
+puts "=" * 40
+puts
+puts "The run_and_clean method executes both phases in a single operation."
+puts "Key benefits:"
+puts "  - Single progress display session for both phases"
+puts "  - Clean always runs, even if run fails (resource release)"
+puts "  - Cleaner API for the common use case"
+puts
+
+# Reset for new demonstration
+Taski::Task.reset!
+
+puts "--- Using run_and_clean ---"
+puts "This is equivalent to calling run followed by clean, but in a single operation."
+puts
+
+CreateRelease.run_and_clean
+
+puts
+puts "Both run and clean phases completed in a single call!"
+puts
+
+# Demonstrate error handling
+Taski::Task.reset!
+
+puts "--- Error Handling Demo ---"
+puts "When run fails, clean is still executed for resource release."
+puts
+
+# Task that fails during run
+class FailingBuild < Taski::Task
+  exports :result
+
+  def run
+    puts "[FailingBuild] Starting build..."
+    raise StandardError, "Build failed: missing dependencies"
+  end
+
+  def clean
+    puts "[FailingBuild] Cleaning up partial build artifacts..."
+  end
+end
+
+begin
+  FailingBuild.run_and_clean
+rescue => e
+  puts "[Error caught] #{e.message}"
+end
+
+puts
+puts "Notice: clean was still executed despite run failing!"

data/examples/group_demo.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taski"
+
+# Demo for group blocks in progress display
+# Run with: ruby examples/group_demo.rb
+#
+# Groups organize output messages within a task into logical phases,
+# displayed as children of the task in the progress tree.
+
+class ConfigTask < Taski::Task
+  exports :config
+
+  def run
+    group("Loading configuration") do
+      puts "Reading config file..."
+      sleep(0.2)
+      puts "Parsing YAML..."
+      sleep(0.1)
+      puts "Config loaded"
+    end
+
+    @config = {
+      database_url: "postgresql://localhost/myapp",
+      redis_url: "redis://localhost:6379"
+    }
+  end
+end
+
+class BuildTask < Taski::Task
+  exports :artifacts
+
+  def run
+    ConfigTask.config  # Ensure config is loaded
+
+    group("Compiling source") do
+      puts "Analyzing dependencies..."
+      sleep(0.2)
+      puts "Compiling 42 files..."
+      sleep(0.3)
+      puts "Compilation complete"
+    end
+
+    group("Running tests") do
+      puts "Running unit tests..."
+      sleep(0.2)
+      puts "Running integration tests..."
+      sleep(0.2)
+      puts "All 128 tests passed"
+    end
+
+    group("Bundling assets") do
+      puts "Minifying JavaScript..."
+      sleep(0.1)
+      puts "Optimizing images..."
+      sleep(0.2)
+      puts "Assets bundled"
+    end
+
+    @artifacts = ["app.js", "app.css", "images/"]
+  end
+end
+
+class DeployTask < Taski::Task
+  exports :deploy_url
+
+  def run
+    artifacts = BuildTask.artifacts
+
+    group("Preparing deployment") do
+      puts "Creating deployment package..."
+      sleep(0.2)
+      puts "Package size: 12.5 MB"
+    end
+
+    group("Uploading to server") do
+      puts "Connecting to server..."
+      sleep(0.1)
+      puts "Uploading #{artifacts.size} artifacts..."
+      sleep(0.3)
+      puts "Upload complete"
+    end
+
+    group("Starting application") do
+      puts "Stopping old instance..."
+      sleep(0.1)
+      puts "Starting new instance..."
+      sleep(0.2)
+      puts "Health check passed"
+    end
+
+    @deploy_url = "https://app.example.com"
+  end
+end
+
+# Show tree structure before execution
+puts "Task Tree Structure:"
+puts "=" * 60
+puts DeployTask.tree
+puts "=" * 60
+puts
+
+# Reset for execution
+DeployTask.reset!
+
+# Execute with progress display
+url = DeployTask.deploy_url
+
+puts "\n"
+puts "=" * 60
+puts "Deployment completed!"
+puts "Application URL: #{url}"

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!"