taski 0.5.0 → 0.7.1

data/examples/README.md

@@ -34,36 +34,36 @@ ruby examples/section_demo.rb
 
 ---
 
-### 3. context_demo.rb - Runtime Context and Options
+### 3. args_demo.rb - Runtime Args and Options
 
-Access execution context and pass custom options to tasks.
+Access execution args and pass custom options to tasks.
 
 ```bash
-ruby examples/context_demo.rb
+ruby examples/args_demo.rb
 ```
 
 **Covers:**
-- User-defined options via `run(context: {...})`
-- `Taski.context[:key]` for option access
-- `Taski.context.fetch(:key, default)` for defaults
-- `Taski.context.working_directory`
-- `Taski.context.started_at`
-- `Taski.context.root_task`
+- User-defined options via `run(args: {...})`
+- `Taski.args[:key]` for option access
+- `Taski.args.fetch(:key, default)` for defaults
+- `Taski.args.working_directory`
+- `Taski.args.started_at`
+- `Taski.args.root_task`
 
 ---
 
-### 4. reexecution_demo.rb - Cache Control
+### 4. reexecution_demo.rb - Scope-Based Execution
 
-Understand caching behavior and re-execution patterns.
+Understand scope-based execution and caching behavior.
 
 ```bash
-ruby examples/reexecution_demo.rb
+TASKI_PROGRESS_DISABLE=1 ruby examples/reexecution_demo.rb
 ```
 
 **Covers:**
-- Default caching behavior
-- `Task.new` for fresh instances
-- `Task.reset!` for clearing caches
+- Fresh execution for each class method call
+- Instance-level caching with `Task.new`
+- Scope-based dependency caching
 
 ---
 
@@ -97,16 +97,64 @@ ruby examples/parallel_progress_demo.rb
 
 ---
 
+### 7. clean_demo.rb - Lifecycle Management
+
+Demonstrates resource cleanup with clean methods.
+
+```bash
+ruby examples/clean_demo.rb
+```
+
+**Covers:**
+- Defining `clean` methods for resource cleanup
+- Reverse dependency order execution
+- `run_and_clean` combined operation
+
+---
+
+### 8. system_call_demo.rb - Subprocess Output
+
+Capture subprocess output in progress display.
+
+```bash
+ruby examples/system_call_demo.rb
+```
+
+**Covers:**
+- `system()` output capture
+- Streaming output display
+- Parallel subprocess execution
+
+---
+
+### 9. nested_section_demo.rb - Nested Sections
+
+Sections that depend on other tasks for implementation selection.
+
+```bash
+TASKI_PROGRESS_DISABLE=1 ruby examples/nested_section_demo.rb
+```
+
+**Covers:**
+- Section inside Section
+- Dynamic implementation selection
+- Complex dependency hierarchies
+
+---
+
 ## Quick Reference
 
 | Example | Feature | Complexity |
 |---------|---------|------------|
 | quick_start | Exports API | Basic |
 | section_demo | Section API | Intermediate |
-| context_demo | Context API | Intermediate |
-| reexecution_demo | Cache Control | Intermediate |
+| args_demo | Args API | Intermediate |
+| reexecution_demo | Scope-Based Execution | Intermediate |
 | data_pipeline_demo | ETL Pipeline | Advanced |
 | parallel_progress_demo | Progress Display | Advanced |
+| clean_demo | Lifecycle Management | Intermediate |
+| system_call_demo | Subprocess Output | Advanced |
+| nested_section_demo | Nested Sections | Advanced |
 
 ## Running All Examples
 

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

@@ -129,7 +129,7 @@ class EnrichWithActivities < Taski::Task
 
     activities_by_user = activities.group_by { |a| a[:user_id] }
       .transform_values do |records|
-      records.to_h { |r| [r[:action], r[:count]] }
+        records.to_h { |r| [r[:action], r[:count]] }
     end
 
     @users_with_activities = users.map do |user|

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