taski 0.4.2 → 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/data_pipeline_demo.rb

@@ -9,7 +9,7 @@
 # - Data transformation and aggregation
 #
 # Run: ruby examples/data_pipeline_demo.rb
-# With progress: TASKI_FORCE_PROGRESS=1 ruby examples/data_pipeline_demo.rb
+# Disable progress: TASKI_PROGRESS_DISABLE=1 ruby examples/data_pipeline_demo.rb
 
 require_relative "../lib/taski"
 
@@ -227,5 +227,5 @@ puts "\nKey concepts demonstrated:"
 puts "  - DataSourceSection: Switch between production/test data"
 puts "  - ReportFormatSection: Switch output format (text/JSON)"
 puts "  - Parallel execution of independent transforms"
-puts "\nTry with progress display:"
-puts "  TASKI_FORCE_PROGRESS=1 ruby examples/data_pipeline_demo.rb"
+puts "\nTo disable progress display:"
+puts "  TASKI_PROGRESS_DISABLE=1 ruby examples/data_pipeline_demo.rb"

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/nested_section_demo.rb

@@ -0,0 +1,161 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taski"
+
+# Demo for nested Sections (Section inside Section)
+# Run with: ruby examples/nested_section_demo.rb
+
+# Configuration loader task - determines which storage to use
+class StorageConfig < Taski::Task
+  exports :use_s3
+
+  def run
+    puts "Loading storage configuration..."
+    sleep(0.4)
+    puts "Checking cloud credentials..."
+    sleep(0.3)
+    puts "Validating storage policies..."
+    sleep(0.3)
+    # Simulate config loading - use local storage by default
+    @use_s3 = ENV["USE_S3"] == "1"
+  end
+end
+
+# Inner Section: Storage backend selection (depends on StorageConfig)
+class StorageSection < Taski::Section
+  interfaces :storage_client
+
+  def impl
+    # Use config task result to decide implementation
+    if StorageConfig.use_s3
+      S3Storage
+    else
+      LocalStorage
+    end
+  end
+
+  class S3Storage < Taski::Task
+    def run
+      puts "Connecting to S3..."
+      sleep(1.0)
+      @storage_client = "s3://bucket/data"
+    end
+  end
+
+  class LocalStorage < Taski::Task
+    def run
+      puts "Initializing local filesystem..."
+      sleep(0.5)
+      puts "Mounting volumes..."
+      sleep(0.5)
+      puts "Local storage ready"
+      sleep(0.3)
+      @storage_client = "/var/data"
+    end
+  end
+end
+
+# Database configuration loader - determines which database to use
+class DatabaseConfig < Taski::Task
+  exports :use_prod
+
+  def run
+    puts "Loading database configuration..."
+    sleep(0.3)
+    puts "Checking environment variables..."
+    sleep(0.3)
+    puts "Resolving database endpoints..."
+    sleep(0.4)
+    # Simulate config loading - use dev database by default
+    @use_prod = ENV["USE_PROD_DB"] == "1"
+  end
+end
+
+# Outer Section: Database selection (depends on Storage and DatabaseConfig)
+class DatabaseSection < Taski::Section
+  interfaces :connection_string
+
+  def impl
+    # Use config task result to decide implementation
+    if DatabaseConfig.use_prod
+      ProductionDB
+    else
+      DevelopmentDB
+    end
+  end
+
+  class ProductionDB < Taski::Task
+    def run
+      # Production DB also needs storage for backups
+      storage = StorageSection.storage_client
+      puts "Connecting to production database (backup: #{storage})..."
+      sleep(0.8)
+      @connection_string = "postgresql://prod-server:5432/myapp"
+    end
+  end
+
+  class DevelopmentDB < Taski::Task
+    def run
+      # Dev DB uses storage for test data
+      storage = StorageSection.storage_client
+      puts "Initializing dev database connection..."
+      sleep(0.4)
+      puts "Loading test fixtures from #{storage}..."
+      sleep(0.5)
+      puts "Dev database ready"
+      sleep(0.3)
+      @connection_string = "postgresql://localhost:5432/myapp_dev"
+    end
+  end
+end
+
+# Task that uses the database
+class FetchData < Taski::Task
+  exports :data
+
+  def run
+    db = DatabaseSection.connection_string
+    puts "Connecting to #{db}..."
+    sleep(0.3)
+    puts "Querying records..."
+    sleep(0.4)
+    puts "Processing results..."
+    sleep(0.3)
+    @data = ["item1", "item2", "item3"]
+  end
+end
+
+# Main application task
+class Application < Taski::Task
+  exports :result
+
+  def run
+    data = FetchData.data
+    puts "Validating #{data.size} items..."
+    sleep(0.3)
+    puts "Transforming data..."
+    sleep(0.4)
+    puts "Finalizing results..."
+    sleep(0.3)
+    @result = "Processed: #{data.join(", ")}"
+  end
+end
+
+# Show tree structure before execution
+puts "Nested Section Tree Structure:"
+puts "=" * 70
+puts Application.tree
+puts "=" * 70
+puts
+
+# Reset for execution
+Application.reset!
+
+# Execute
+result = Application.result
+
+puts "\n"
+puts "=" * 70
+puts "Execution completed!"
+puts "Result: #{result}"

data/examples/parallel_progress_demo.rb

@@ -4,7 +4,7 @@
 require_relative "../lib/taski"
 
 # Demo tasks that simulate parallel execution with progress display
-# Run with: TASKI_FORCE_PROGRESS=1 ruby examples/parallel_progress_demo.rb
+# Run with: ruby examples/parallel_progress_demo.rb
 
 class DownloadLayer1 < Taski::Task
   exports :layer1_data