taski 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e44ea93464ceaf8994d761cec75cf4d32df7cdb8f90d25b4cfcae5be7f8a586
-  data.tar.gz: 8a1b5fae85bbffb28756f2e13b3f98c2cb8023c76346b5da722ac55e87ef3cc5
+  metadata.gz: 28f2e52366511da4606df64a169c804712fcf4398b55a7b7d6430a1367cc183d
+  data.tar.gz: 97cc63c767ceaf7dda2fbb4345876c47d1fb1bf7e0395c8a2a0369bc8585e817
 SHA512:
-  metadata.gz: '037285b1bc19edd6d674f6748674fa8443c0cb40d5199de86bdfa3696c1597308d69ff5236a7114c43cf666a27e62f5c4111c5a36301736c4fdac98cdd65b4c4'
-  data.tar.gz: afa967d630b56f9de1f4974879533572d06c42d574dce6bea69da9635ce69e06251af555168ff0b3475e95d5a1d6d07e8951e6052f0f6e04291d07b15d23239b
+  metadata.gz: 4558c7e5ab3ae48301da573a0d2dffa935ecf2bdf7f04ccce1b92add5ea45b3aea1b562dcce0c6356d28b7eacd58fcdca030a9a2748fbafdda9d9046b5a09213
+  data.tar.gz: f440abca3014be0bffdd34cb8440f197b55403fc938660a8eb311e1bb6c64127bf9d033335d7e52f71cefec534ae4b6e41e2b83164d76b893d3a3c8f692bc221

data/README.md

@@ -99,7 +99,7 @@ EnvironmentConfig.build
 
 ### When to Use Each API
 
-- **Define API**: Best for dynamic runtime dependencies. Cannot contain side effects in definition blocks.
+- **Define API**: Best for dynamic runtime dependencies. Cannot contain side effects in definition blocks. Dependencies are analyzed at class definition time, not runtime.
 - **Exports API**: Ideal for static dependencies. Supports side effects in build methods.
 
 | Use Case | API | Example |
@@ -109,6 +109,8 @@ EnvironmentConfig.build
 | Side effects | Exports | Database connections, I/O |
 | Conditional processing | Define | Algorithm selection |
 
+**Note**: Define API analyzes dependencies when the class is defined. Conditional dependencies like `ENV['USE_NEW'] ? TaskA : TaskB` will only include the task selected at class definition time, not runtime.
+
 ## ✨ Key Features
 
 - **Automatic Dependency Resolution**: Dependencies detected through static analysis
@@ -172,6 +174,29 @@ WebServer.clean
 # => Database disconnected
 ```
 
+### Clean Method Idempotency
+
+**Important**: The `clean` method must be idempotent - safe to call multiple times without errors.
+
+```ruby
+class FileTask < Taski::Task
+  exports :output_file
+
+  def build
+    @output_file = '/tmp/data.csv'
+    File.write(@output_file, process_data)
+  end
+
+  def clean
+    # ❌ Bad: Raises error if file doesn't exist
+    # File.delete(@output_file)
+    
+    # ✅ Good: Check before delete
+    File.delete(@output_file) if File.exist?(@output_file)
+  end
+end
+```
+
 ### Error Handling
 
 ```ruby

data/examples/README.md

@@ -0,0 +1,57 @@
+# Taski Examples
+
+Learn Taski through practical examples, from basic concepts to advanced patterns.
+
+## Getting Started
+
+Start with these examples in order:
+
+### 1. **[quick_start.rb](quick_start.rb)** - Your First Taski Program
+- Basic task definition with Exports API
+- Automatic dependency resolution
+- Simple task execution
+
+```bash
+ruby examples/quick_start.rb
+```
+
+### 2. **[progress_demo.rb](progress_demo.rb)** - Rich CLI Progress Display
+- Animated spinner with ANSI colors
+- Real-time output capture and 5-line tail
+- Production build scenarios
+- TTY detection for clean file output
+
+```bash
+# Interactive mode with rich spinner
+ruby examples/progress_demo.rb
+
+# Clean output mode (no spinner)
+ruby examples/progress_demo.rb > build.log 2>&1
+cat build.log
+```
+
+### 3. **[advanced_patterns.rb](advanced_patterns.rb)** - Complex Dependency Patterns
+- Mixed Exports API and Define API usage
+- Environment-specific dependencies
+- Feature flags and conditional logic
+- Task reset and rebuild scenarios
+
+```bash
+ruby examples/advanced_patterns.rb
+```
+
+## Key Concepts Demonstrated
+
+- **Exports API**: Static dependencies with `exports :property`
+- **Define API**: Dynamic dependencies with `define :property, -> { ... }`
+- **Progress Display**: Rich terminal output with spinners and colors
+- **Output Capture**: Tail-style display of task output
+- **Environment Configuration**: Different behavior based on runtime settings
+- **Error Handling**: Graceful failure with progress indicators
+
+## Next Steps
+
+After exploring these examples:
+- Read the main documentation
+- Examine the test files for more usage patterns
+- Check out the source code in `lib/taski/`

data/examples/{complex_example.rb → advanced_patterns.rb}

@@ -1,8 +1,22 @@
 #!/usr/bin/env ruby
-# Complex example from README showing both APIs
+# frozen_string_literal: true
+
+# Taski Advanced Patterns
+#
+# This example demonstrates advanced Taski patterns:
+# - Mixed usage of Exports API and Define API
+# - Environment-specific dependency resolution
+# - Feature flag integration with dynamic dependencies
+# - Task reset and rebuild scenarios
+# - Conditional dependency evaluation
+#
+# Run: ruby examples/advanced_patterns.rb
 
 require_relative "../lib/taski"
 
+puts "⚡ Advanced Taski Patterns"
+puts "=" * 40
+
 # Mock classes for the example
 class ProductionDB < Taski::Task
   exports :connection_string
@@ -81,8 +95,6 @@ class Application < Taski::Task
 end
 
 # Test different environments
-puts "=== Complex Example ==="
-
 puts "\n1. Development Environment (default):"
 ENV.delete("RAILS_ENV")
 ENV.delete("FEATURE_REDIS_CACHE")

data/examples/progress_demo.rb

@@ -0,0 +1,166 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Progress Display Demo
+#
+# This comprehensive example demonstrates all progress display features:
+# 1. Basic spinner animation with success/failure indicators
+# 2. Output capture with 5-line tail display
+# 3. Real-world build scenario with external command simulation
+# 4. TTY detection for clean file output
+#
+# Run: ruby examples/progress_demo.rb
+# Try: ruby examples/progress_demo.rb > build.log 2>&1 && cat build.log
+
+require_relative "../lib/taski"
+
+puts "🎯 Taski Progress Display Demo"
+puts "=" * 50
+
+# SECTION 1: Basic Spinner Animation
+puts "\n📍 SECTION 1: Basic Spinner & Success/Failure Indicators"
+puts "-" * 50
+
+class ConfigTask < Taski::Task
+  exports :database_url, :cache_url
+
+  def build
+    sleep 0.8
+    @database_url = "postgres://localhost/myapp"
+    @cache_url = "redis://localhost:6379"
+  end
+end
+
+class DatabaseTask < Taski::Task
+  exports :connection
+
+  def build
+    sleep 1.2
+    @connection = "Connected to #{ConfigTask.database_url}"
+  end
+end
+
+class ApplicationTask < Taski::Task
+  exports :status
+
+  def build
+    sleep 1.0
+    db = DatabaseTask.connection
+    @status = "App ready! #{db}"
+  end
+end
+
+ApplicationTask.build
+puts "🎉 Application Status: #{ApplicationTask.status}"
+
+# SECTION 2: Output Capture Demo
+puts "\n📍 SECTION 2: Output Capture with 5-Line Tail"
+puts "-" * 50
+
+class VerboseTask < Taski::Task
+  exports :result
+
+  def build
+    puts "Starting task initialization..."
+    sleep 0.3
+
+    puts "Loading configuration files..."
+    puts "Connecting to database..."
+    puts "Connection established: localhost:5432"
+    sleep 0.3
+
+    puts "Running initial checks..."
+    puts "Checking schema version..."
+    puts "Schema is up to date"
+    puts "Performing data validation..."
+    puts "Validating user records..."
+    puts "Validating product records..."
+    puts "All validations passed"
+    sleep 0.4
+
+    puts "Task completed successfully!"
+    @result = "All operations completed"
+  end
+end
+
+VerboseTask.build
+puts "📊 Verbose Task Result: #{VerboseTask.result}"
+
+# SECTION 3: Production Build Scenario
+puts "\n📍 SECTION 3: Production Build Scenario"
+puts "-" * 50
+
+class CompileTask < Taski::Task
+  exports :result
+
+  def build
+    puts "Starting compilation process..."
+    sleep 0.8
+
+    puts "Checking source files..."
+    puts "Found: main.c, utils.c, config.h"
+    sleep 0.6
+
+    puts "Running gcc compilation..."
+    puts "gcc -Wall -O2 -c main.c"
+    puts "gcc -Wall -O2 -c utils.c"
+    puts "main.c: In function 'main':"
+    puts "main.c:42: warning: unused variable 'temp'"
+    puts "utils.c: In function 'parse_config':"
+    puts "utils.c:15: warning: implicit declaration of function 'strcpy'"
+    sleep 0.8
+
+    puts "Linking objects..."
+    puts "gcc -o myapp main.o utils.o"
+    puts "Compilation successful!"
+
+    @result = "myapp binary created"
+  end
+end
+
+class TestTask < Taski::Task
+  exports :test_result
+
+  def build
+    puts "Running test suite..."
+    sleep 0.2
+
+    (1..8).each do |i|
+      puts "Test #{i}/8: #{["PASS", "PASS", "FAIL", "PASS", "PASS", "PASS", "PASS", "PASS"][i - 1]}"
+      sleep 0.4
+    end
+
+    puts "Test summary: 7/8 passed, 1 failed"
+    @test_result = "Tests completed with 1 failure"
+  end
+end
+
+CompileTask.build
+puts "📦 Compilation: #{CompileTask.result}"
+
+TestTask.build
+puts "🧪 Test Result: #{TestTask.test_result}"
+
+# SECTION 4: Error Handling Demo
+puts "\n📍 SECTION 4: Error Handling Demo"
+puts "-" * 50
+
+class FailingTask < Taski::Task
+  def build
+    puts "Attempting network connection..."
+    sleep 1.0  # Watch it spin before failing
+    puts "Connection timeout after 30 seconds"
+    puts "Retrying connection..."
+    sleep 0.5
+    raise StandardError, "Network connection failed!"
+  end
+end
+
+begin
+  FailingTask.build
+rescue Taski::TaskBuildError => e
+  puts "🛡️  Error handled gracefully: #{e.message}"
+end
+
+puts "\n✨ Demo Complete!"
+puts "Note: Rich spinner display only appears in terminals, not when output is redirected."

data/examples/{readme_example.rb → quick_start.rb}

@@ -1,8 +1,20 @@
 #!/usr/bin/env ruby
-# Quick Start example from README
+# frozen_string_literal: true
+
+# Taski Quick Start Guide
+#
+# This example demonstrates the fundamentals of Taski:
+# - Task definition with the Exports API
+# - Automatic dependency resolution
+# - Simple task execution
+#
+# Run: ruby examples/quick_start.rb
 
 require_relative "../lib/taski"
 
+puts "🚀 Taski Quick Start"
+puts "=" * 30
+
 # Simple static dependency using Exports API
 class DatabaseSetup < Taski::Task
   exports :connection_string
@@ -24,7 +36,6 @@ class APIServer < Taski::Task
 end
 
 # Execute - dependencies are resolved automatically
-puts "=== Quick Start Example ==="
 APIServer.build
 
-puts "\nResult: APIServer running on port #{APIServer.port}"
+puts "\n✅ Result: APIServer running on port #{APIServer.port}"

data/examples/tree_demo.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Tree Display Demo
+#
+# This example demonstrates the tree display functionality that shows
+# task dependency relationships in a visual tree format.
+#
+# Run: ruby examples/tree_demo.rb
+
+require_relative "../lib/taski"
+
+puts "🌲 Taski Tree Display Demo"
+puts "=" * 40
+
+# Create a dependency chain for demonstration
+class Database < Taski::Task
+  exports :connection_string
+
+  def build
+    @connection_string = "postgres://localhost/myapp"
+  end
+end
+
+class Cache < Taski::Task
+  exports :redis_url
+
+  def build
+    @redis_url = "redis://localhost:6379"
+  end
+end
+
+class Config < Taski::Task
+  exports :settings
+
+  def build
+    @settings = {
+      database: Database.connection_string,
+      cache: Cache.redis_url,
+      port: 3000
+    }
+  end
+end
+
+class Logger < Taski::Task
+  exports :log_level
+
+  def build
+    @log_level = "info"
+  end
+end
+
+class WebServer < Taski::Task
+  exports :server_instance
+
+  def build
+    @server_instance = "WebServer configured with #{Config.settings[:database]} and #{Logger.log_level}"
+  end
+end
+
+class Application < Taski::Task
+  def build
+    puts "Starting application..."
+    puts "Web server: #{WebServer.server_instance}"
+    puts "Config: #{Config.settings}"
+  end
+end
+
+puts "\n📊 Application Dependency Tree:"
+puts Application.tree
+
+puts "\n🔍 Individual Component Trees:"
+puts "\nWebServer dependencies:"
+puts WebServer.tree
+
+puts "\nConfig dependencies:"
+puts Config.tree
+
+puts "\n▶️  Building Application (to verify dependencies work):"
+Application.build

data/lib/taski/logger.rb

@@ -48,11 +48,16 @@ module Taski
     # Log task build start event
     # @param task_name [String] Name of the task being built
     # @param dependencies [Array] List of task dependencies
-    def task_build_start(task_name, dependencies: [])
-      info("Task build started",
+    # @param args [Hash] Build arguments for parametrized builds
+    def task_build_start(task_name, dependencies: [], args: nil)
+      context = {
         task: task_name,
         dependencies: dependencies.size,
-        dependency_names: dependencies.map { |dep| dep.is_a?(Hash) ? dep[:klass].inspect : dep.inspect })
+        dependency_names: dependencies.map { |dep| dep.is_a?(Hash) ? dep[:klass].inspect : dep.inspect }
+      }
+      context[:args] = args if args && !args.empty?
+
+      info("Task build started", **context)
     end
 
     # Log task build completion event
@@ -181,6 +186,12 @@ module Taski
       @logger ||= Logger.new
     end
 
+    # Get the current progress display instance (always enabled)
+    # @return [ProgressDisplay] Current progress display instance
+    def progress_display
+      @progress_display ||= ProgressDisplay.new(force_enable: ENV["TASKI_FORCE_PROGRESS"] == "1")
+    end
+
     # Configure the logger with new settings
     # @param level [Symbol] Log level (:debug, :info, :warn, :error)
     # @param output [IO] Output destination

data/lib/taski/progress_display.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Taski
+  # Terminal control operations with ANSI escape sequences
+  class TerminalController
+    # ANSI escape sequences
+    MOVE_UP = "\033[A"
+    CLEAR_LINE = "\033[K"
+    MOVE_UP_AND_CLEAR = "#{MOVE_UP}#{CLEAR_LINE}"
+
+    def initialize(output)
+      @output = output
+    end
+
+    def clear_lines(count)
+      return if count == 0
+
+      count.times { @output.print MOVE_UP_AND_CLEAR }
+    end
+
+    def puts(text)
+      @output.puts text
+    end
+
+    def print(text)
+      @output.print text
+    end
+
+    def flush
+      @output.flush
+    end
+  end
+
+  # Spinner animation with dots-style characters
+  class SpinnerAnimation
+    SPINNER_CHARS = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"].freeze
+    FRAME_DELAY = 0.1
+
+    def initialize
+      @frame = 0
+      @running = false
+      @thread = nil
+    end
+
+    def start(terminal, task_name, &display_callback)
+      return if @running
+
+      @running = true
+      @frame = 0
+
+      @thread = Thread.new do
+        while @running
+          current_char = SPINNER_CHARS[@frame % SPINNER_CHARS.length]
+          display_callback&.call(current_char, task_name)
+
+          @frame += 1
+          sleep FRAME_DELAY
+        end
+      rescue
+        # Silently handle thread errors
+      end
+    end
+
+    def stop
+      @running = false
+      @thread&.join(0.2)
+      @thread = nil
+    end
+
+    def running?
+      @running
+    end
+  end
+
+  # Captures stdout and maintains last N lines like tail -f
+  class OutputCapture
+    MAX_LINES = 10
+    DISPLAY_LINES = 5
+
+    def initialize(main_output)
+      @main_output = main_output
+      @buffer = []
+      @capturing = false
+      @original_stdout = nil
+      @pipe_reader = nil
+      @pipe_writer = nil
+      @capture_thread = nil
+    end
+
+    def start
+      return if @capturing
+
+      @buffer.clear
+      setup_stdout_redirection
+      @capturing = true
+
+      start_capture_thread
+    end
+
+    def stop
+      return unless @capturing
+
+      @capturing = false
+
+      # Restore stdout
+      restore_stdout
+
+      # Clean up pipes and thread
+      cleanup_capture_thread
+      cleanup_pipes
+    end
+
+    def last_lines
+      @buffer.last(DISPLAY_LINES)
+    end
+
+    def capturing?
+      @capturing
+    end
+
+    private
+
+    def setup_stdout_redirection
+      @original_stdout = $stdout
+      @pipe_reader, @pipe_writer = IO.pipe
+      $stdout = @pipe_writer
+    end
+
+    def restore_stdout
+      return unless @original_stdout
+
+      $stdout = @original_stdout
+      @original_stdout = nil
+    end
+
+    def start_capture_thread
+      @capture_thread = Thread.new do
+        while (line = @pipe_reader.gets)
+          line = line.chomp
+          next if line.empty?
+          next if skip_line?(line)
+
+          add_line_to_buffer(line)
+        end
+      rescue IOError
+        # Pipe closed, normal termination
+      end
+    end
+
+    def skip_line?(line)
+      # Skip logger lines (they appear separately)
+      line.match?(/^\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}\]/)
+    end
+
+    def add_line_to_buffer(line)
+      @buffer << line
+      @buffer.shift while @buffer.length > MAX_LINES
+    end
+
+    def cleanup_capture_thread
+      @capture_thread&.join(0.1)
+      @capture_thread = nil
+    end
+
+    def cleanup_pipes
+      [@pipe_writer, @pipe_reader].each do |pipe|
+        pipe&.close
+      rescue IOError
+        # Already closed, ignore
+      end
+      @pipe_writer = @pipe_reader = nil
+    end
+  end
+
+  # Represents task execution status
+  class TaskStatus
+    attr_reader :name, :duration, :error
+
+    def initialize(name:, duration: nil, error: nil)
+      @name = name
+      @duration = duration
+      @error = error
+    end
+
+    def success?
+      @error.nil?
+    end
+
+    def failure?
+      !success?
+    end
+
+    def duration_ms
+      return nil unless @duration
+      (@duration * 1000).round(1)
+    end
+
+    def icon
+      success? ? "✅" : "❌"
+    end
+
+    def format_duration
+      return "" unless duration_ms
+      "(#{duration_ms}ms)"
+    end
+  end
+
+  # Main progress display controller
+  class ProgressDisplay
+    # ANSI colors
+    COLORS = {
+      reset: "\033[0m",
+      bold: "\033[1m",
+      dim: "\033[2m",
+      cyan: "\033[36m",
+      green: "\033[32m",
+      red: "\033[31m"
+    }.freeze
+
+    def initialize(output: $stdout, force_enable: nil)
+      @output = output
+      @terminal = TerminalController.new(output)
+      @spinner = SpinnerAnimation.new
+      @output_capture = OutputCapture.new(output)
+
+      # Enable if TTY or force enabled or environment variable set
+      @enabled = force_enable.nil? ? (output.tty? || ENV["TASKI_FORCE_PROGRESS"] == "1") : force_enable
+
+      @completed_tasks = []
+      @current_display_lines = 0
+    end
+
+    def start_task(task_name, dependencies: [])
+      puts "DEBUG: start_task called for #{task_name}, enabled: #{@enabled}" if ENV["TASKI_DEBUG"]
+      return unless @enabled
+
+      clear_current_display
+      @output_capture.start
+
+      start_spinner_display(task_name)
+    end
+
+    def complete_task(task_name, duration:)
+      return unless @enabled
+
+      status = TaskStatus.new(name: task_name, duration: duration)
+      finish_task(status)
+    end
+
+    def fail_task(task_name, error:, duration:)
+      return unless @enabled
+
+      status = TaskStatus.new(name: task_name, duration: duration, error: error)
+      finish_task(status)
+    end
+
+    def clear
+      return unless @enabled
+
+      @spinner.stop
+      @output_capture.stop
+      clear_current_display
+
+      # Display final summary of all completed tasks
+      if @completed_tasks.any?
+        @completed_tasks.each do |status|
+          @terminal.puts format_completed_task(status)
+        end
+        @terminal.flush
+      end
+
+      @completed_tasks.clear
+      @current_display_lines = 0
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    private
+
+    def start_spinner_display(task_name)
+      @spinner.start(@terminal, task_name) do |spinner_char, name|
+        display_current_state(spinner_char, name)
+      end
+    end
+
+    def display_current_state(spinner_char, task_name)
+      clear_current_display
+
+      lines_count = 0
+
+      # Only display current task with spinner (no past completed tasks during execution)
+      @terminal.puts format_current_task(spinner_char, task_name)
+      lines_count += 1
+
+      # Display output lines
+      @output_capture.last_lines.each do |line|
+        @terminal.puts format_output_line(line)
+        lines_count += 1
+      end
+
+      @current_display_lines = lines_count
+      @terminal.flush
+    end
+
+    def finish_task(status)
+      @spinner.stop
+
+      # Capture output before stopping
+      captured_output = @output_capture.last_lines
+      @output_capture.stop
+      clear_current_display
+
+      # In test environments (when terminal is StringIO), include captured output
+      if @terminal.is_a?(StringIO) && captured_output.any?
+        captured_output.each do |line|
+          @terminal.puts line.chomp
+        end
+      end
+
+      @completed_tasks << status
+      display_final_state
+    end
+
+    def display_final_state
+      # Only display the newly completed task (last one)
+      if @completed_tasks.any?
+        latest_task = @completed_tasks.last
+        @terminal.puts format_completed_task(latest_task)
+      end
+      @terminal.flush
+      @current_display_lines = 1  # Only one line for the latest task
+    end
+
+    def format_completed_task(status)
+      color = status.success? ? COLORS[:green] : COLORS[:red]
+      "#{color}#{COLORS[:bold]}#{status.icon} #{status.name}#{COLORS[:reset]} #{COLORS[:dim]}#{status.format_duration}#{COLORS[:reset]}"
+    end
+
+    def format_current_task(spinner_char, task_name)
+      "#{COLORS[:cyan]}#{spinner_char}#{COLORS[:reset]} #{COLORS[:bold]}#{task_name}#{COLORS[:reset]}"
+    end
+
+    def format_output_line(line)
+      "  #{COLORS[:dim]}#{line}#{COLORS[:reset]}"
+    end
+
+    def clear_current_display
+      @terminal.clear_lines(@current_display_lines)
+      @current_display_lines = 0
+    end
+  end
+end

data/lib/taski/task/base.rb

@@ -41,6 +41,51 @@ module Taski
       def __resolve__
         @__resolve__ ||= {}
       end
+
+      # Display dependency tree for this task
+      # @param prefix [String] Current indentation prefix
+      # @param visited [Set] Set of visited classes to prevent infinite loops
+      # @return [String] Formatted dependency tree
+      def tree(prefix = "", visited = Set.new)
+        return "#{prefix}#{name} (circular)\n" if visited.include?(self)
+
+        visited = visited.dup
+        visited << self
+
+        result = "#{prefix}#{name}\n"
+
+        dependencies = (@dependencies || []).uniq { |dep| extract_class(dep) }
+        dependencies.each_with_index do |dep, index|
+          dep_class = extract_class(dep)
+          is_last = index == dependencies.length - 1
+
+          connector = is_last ? "└── " : "├── "
+          child_prefix = prefix + (is_last ? "    " : "│   ")
+
+          # For the dependency itself, we want to use the connector
+          # For its children, we want to use the child_prefix
+          dep_tree = dep_class.tree(child_prefix, visited)
+          # Replace the first line (which has child_prefix) with the proper connector
+          dep_lines = dep_tree.lines
+          if dep_lines.any?
+            # Replace the first line prefix with connector
+            first_line = dep_lines[0]
+            fixed_first_line = first_line.sub(/^#{Regexp.escape(child_prefix)}/, prefix + connector)
+            result += fixed_first_line
+            # Add the rest of the lines as-is
+            result += dep_lines[1..].join if dep_lines.length > 1
+          else
+            result += "#{prefix}#{connector}#{dep_class.name}\n"
+          end
+        end
+
+        result
+      end
+
+      private
+
+      include Utils::DependencyUtils
+      private :extract_class
     end
 
     # === Instance Methods ===
@@ -51,6 +96,12 @@ module Taski
       raise NotImplementedError, "You must implement the build method in your task class"
     end
 
+    # Access build arguments passed to parametrized builds
+    # @return [Hash] Build arguments or empty hash if none provided
+    def build_args
+      @build_args || {}
+    end
+
     # Clean method with default empty implementation
     # Subclasses can override this method to implement cleanup logic
     def clean

data/lib/taski/task/define_api.rb

@@ -37,7 +37,19 @@ module Taski
       def create_ref_method_if_needed
         return if method_defined_for_define?(:ref)
 
-        define_singleton_method(:ref) { |klass| Object.const_get(klass) }
+        define_singleton_method(:ref) do |klass_name|
+          # During dependency analysis, track as dependency but defer resolution
+          if Thread.current[TASKI_ANALYZING_DEFINE_KEY]
+            # Create Reference object for deferred resolution
+            reference = Taski::Reference.new(klass_name)
+
+            # Track as dependency by throwing unresolved
+            throw :unresolved, [reference, :deref]
+          else
+            # At runtime, resolve to actual class
+            Object.const_get(klass_name)
+          end
+        end
         mark_method_as_defined(:ref)
       end
 
@@ -80,7 +92,11 @@ module Taski
 
         # Reset resolution state
         classes.each do |task_class|
-          task_class[:klass].instance_variable_set(:@__resolve__, {})
+          klass = task_class[:klass]
+          # Only reset Task classes, not Reference objects
+          if klass.respond_to?(:instance_variable_set) && !klass.is_a?(Taski::Reference)
+            klass.instance_variable_set(:@__resolve__, {})
+          end
         end
 
         classes

data/lib/taski/task/dependency_resolver.rb

@@ -80,17 +80,7 @@ module Taski
 
       # Build detailed error message for circular dependencies
       def build_circular_dependency_message(cycle_path)
-        path_names = cycle_path.map { |klass| klass.name || klass.to_s }
-
-        message = "Circular dependency detected!\n"
-        message += "Cycle: #{path_names.join(" → ")}\n\n"
-        message += "Detailed dependency chain:\n"
-
-        cycle_path.each_cons(2).with_index do |(from, to), index|
-          message += "  #{index + 1}. #{from.name} depends on → #{to.name}\n"
-        end
-
-        message
+        Utils::CircularDependencyHelpers.build_error_message(cycle_path, "dependency")
       end
 
       public
@@ -133,6 +123,11 @@ module Taski
       def dependency_exists?(dep_class)
         (@dependencies || []).any? { |d| d[:klass] == dep_class }
       end
+
+      private
+
+      include Utils::DependencyUtils
+      private :extract_class
     end
   end
 end

data/lib/taski/task/instance_management.rb

@@ -8,9 +8,19 @@ module Taski
       # === Lifecycle Management ===
 
       # Build this task and all its dependencies
-      def build
-        resolve_dependencies.reverse_each do |task_class|
-          task_class.ensure_instance_built
+      # @param args [Hash] Optional arguments for parametrized builds
+      # @return [Task] Returns task instance (singleton or temporary)
+      def build(**args)
+        if args.empty?
+          # Traditional build: singleton instance with caching
+          resolve_dependencies.reverse_each do |task_class|
+            task_class.ensure_instance_built
+          end
+          # Return the singleton instance for consistency
+          instance_variable_get(:@__task_instance)
+        else
+          # Parametrized build: temporary instance without caching
+          build_with_args(args)
         end
       end
 
@@ -41,6 +51,32 @@ module Taski
         reset!
       end
 
+      # === Parametrized Build Support ===
+
+      # Build temporary instance with arguments
+      # @param args [Hash] Build arguments
+      # @return [Task] Temporary task instance
+      def build_with_args(args)
+        # Resolve dependencies first (same as normal build)
+        resolve_dependencies.reverse_each do |task_class|
+          task_class.ensure_instance_built
+        end
+
+        # Create temporary instance with arguments
+        temp_instance = new
+        temp_instance.instance_variable_set(:@build_args, args)
+
+        # Build with logging using common utility
+        Utils::TaskBuildHelpers.with_build_logging(name.to_s,
+          dependencies: @dependencies || [],
+          args: args) do
+          temp_instance.build
+          temp_instance
+        end
+      end
+
+      private :build_with_args
+
       # === Instance Management ===
 
       # Ensure task instance is built (public because called from build)
@@ -93,18 +129,10 @@ module Taski
       # @return [Task] Built task instance
       def build_instance
         instance = new
-        build_start_time = Time.now
-        begin
-          Taski.logger.task_build_start(name.to_s, dependencies: @dependencies || [])
+        Utils::TaskBuildHelpers.with_build_logging(name.to_s,
+          dependencies: @dependencies || []) do
           instance.build
-          duration = Time.now - build_start_time
-          Taski.logger.task_build_complete(name.to_s, duration: duration)
           instance
-        rescue => e
-          duration = Time.now - build_start_time
-          # Log the error with full context
-          Taski.logger.task_build_failed(name.to_s, error: e, duration: duration)
-          raise TaskBuildError, "Failed to build task #{name}: #{e.message}"
         end
       end
 
@@ -129,6 +157,8 @@ module Taski
         end
       end
 
+      private
+
       # Build current dependency path from thread-local storage
       # @return [Array<Class>] Array of classes in the current build path
       def build_current_dependency_path
@@ -150,27 +180,11 @@ module Taski
       # @param cycle_path [Array<Class>] The circular dependency path
       # @return [String] Formatted error message
       def build_runtime_circular_dependency_message(cycle_path)
-        path_names = cycle_path.map { |klass| klass.name || klass.to_s }
-
-        message = "Circular dependency detected!\n"
-        message += "Cycle: #{path_names.join(" → ")}\n\n"
-        message += "The dependency chain is:\n"
-
-        cycle_path.each_cons(2).with_index do |(from, to), index|
-          message += "  #{index + 1}. #{from.name} is trying to build → #{to.name}\n"
-        end
-
-        message += "\nThis creates an infinite loop that cannot be resolved."
-        message
+        Utils::CircularDependencyHelpers.build_error_message(cycle_path, "runtime")
       end
 
-      # Extract class from dependency hash
-      # @param dep [Hash] Dependency information
-      # @return [Class] The dependency class
-      def extract_class(dep)
-        klass = dep[:klass]
-        klass.is_a?(Reference) ? klass.deref : klass
-      end
+      include Utils::DependencyUtils
+      private :extract_class
     end
   end
 end

data/lib/taski/utils.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Taski
+  # Common utility functions for the Taski framework
+  module Utils
+    # Handle circular dependency error message generation
+    module CircularDependencyHelpers
+      # Build detailed error message for circular dependencies
+      # @param cycle_path [Array<Class>] The circular dependency path
+      # @param context [String] Context of the error (dependency, runtime)
+      # @return [String] Formatted error message
+      def self.build_error_message(cycle_path, context = "dependency")
+        path_names = cycle_path.map { |klass| klass.name || klass.to_s }
+
+        message = "Circular dependency detected!\n"
+        message += "Cycle: #{path_names.join(" → ")}\n\n"
+        message += "The #{context} chain is:\n"
+
+        cycle_path.each_cons(2).with_index do |(from, to), index|
+          action = (context == "dependency") ? "depends on" : "is trying to build"
+          message += "  #{index + 1}. #{from.name} #{action} → #{to.name}\n"
+        end
+
+        message += "\nThis creates an infinite loop that cannot be resolved." if context == "dependency"
+        message
+      end
+    end
+
+    # Common dependency utility functions
+    module DependencyUtils
+      # Extract class from dependency hash
+      # @param dep [Hash] Dependency information
+      # @return [Class] The dependency class
+      def extract_class(dep)
+        klass = dep[:klass]
+        klass.is_a?(Reference) ? klass.deref : klass
+      end
+    end
+
+    # Common task build utility functions
+    module TaskBuildHelpers
+      # Format arguments hash for display in error messages
+      # @param args [Hash] Arguments hash
+      # @return [String] Formatted arguments string
+      def self.format_args(args)
+        return "" if args.nil? || args.empty?
+
+        formatted_pairs = args.map do |key, value|
+          "#{key}: #{value.inspect}"
+        end
+        "{#{formatted_pairs.join(", ")}}"
+      end
+
+      # Execute block with comprehensive build logging and progress display
+      # @param task_name [String] Name of the task being built
+      # @param dependencies [Array] List of dependencies
+      # @param args [Hash] Build arguments for parametrized builds
+      # @yield Block to execute with logging
+      # @return [Object] Result of the block execution
+      def self.with_build_logging(task_name, dependencies: [], args: nil)
+        build_start_time = Time.now
+
+        begin
+          # Traditional logging first (before any stdout redirection)
+          Taski.logger.task_build_start(task_name, dependencies: dependencies, args: args)
+
+          # Show progress display if enabled (this may redirect stdout)
+          Taski.progress_display&.start_task(task_name, dependencies: dependencies)
+
+          result = yield
+          duration = Time.now - build_start_time
+
+          # Complete progress display first (this restores stdout)
+          Taski.progress_display&.complete_task(task_name, duration: duration)
+
+          # Then do logging (on restored stdout)
+          begin
+            Taski.logger.task_build_complete(task_name, duration: duration)
+          rescue IOError
+            # If logger fails due to closed stream, write to STDERR instead
+            warn "[#{Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")}] INFO  Taski: Task build completed (task=#{task_name}, duration_ms=#{(duration * 1000).round(2)})"
+          end
+
+          result
+        rescue => e
+          duration = Time.now - build_start_time
+
+          # Complete progress display first (with error)
+          Taski.progress_display&.fail_task(task_name, error: e, duration: duration)
+
+          # Then do error logging (on restored stdout)
+          begin
+            Taski.logger.task_build_failed(task_name, error: e, duration: duration)
+          rescue IOError
+            # If logger fails due to closed stream, write to STDERR instead
+            warn "[#{Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")}] ERROR Taski: Task build failed (task=#{task_name}, error=#{e.message}, duration_ms=#{(duration * 1000).round(2)})"
+          end
+
+          error_message = "Failed to build task #{task_name}"
+          error_message += " with args #{format_args(args)}" if args && !args.empty?
+          error_message += ": #{e.message}"
+          raise TaskBuildError, error_message
+        end
+      end
+    end
+  end
+end

data/lib/taski/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taski
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/lib/taski.rb

@@ -6,8 +6,10 @@ require "monitor"
 require_relative "taski/version"
 require_relative "taski/exceptions"
 require_relative "taski/logger"
+require_relative "taski/progress_display"
 require_relative "taski/reference"
 require_relative "taski/dependency_analyzer"
+require_relative "taski/utils"
 
 # Load Task class components
 require_relative "taski/task/base"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - ahogappa
 bindir: exe
 cert_chain: []
-date: 2025-06-21 00:00:00.000000000 Z
+date: 2025-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -39,18 +39,23 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- examples/complex_example.rb
-- examples/readme_example.rb
+- examples/README.md
+- examples/advanced_patterns.rb
+- examples/progress_demo.rb
+- examples/quick_start.rb
+- examples/tree_demo.rb
 - lib/taski.rb
 - lib/taski/dependency_analyzer.rb
 - lib/taski/exceptions.rb
 - lib/taski/logger.rb
+- lib/taski/progress_display.rb
 - lib/taski/reference.rb
 - lib/taski/task/base.rb
 - lib/taski/task/define_api.rb
 - lib/taski/task/dependency_resolver.rb
 - lib/taski/task/exports_api.rb
 - lib/taski/task/instance_management.rb
+- lib/taski/utils.rb
 - lib/taski/version.rb
 - sig/taski.rbs
 homepage: https://github.com/ahogappa/taski