taski 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c841d7a7a8e632045f42b090be2c6b10a9ef1510c9b9298bc50737f89486f28
-  data.tar.gz: 540f4595d667f191ac2a36464529e324fd56c5a5466dbcc2580b5227030501b5
+  metadata.gz: cddae184fb1f55c69b42995e51c3bf5711d31f978ec383a00a73d2ce3531ca15
+  data.tar.gz: 3e79ca2bf3a6cd163272bbff98ff3b980f3a3b69293607dd45879501d50904c4
 SHA512:
-  metadata.gz: c4b2064e55edde2f504fd8c857efff572faf6de8466983c0081c2ca902c63784c75d121c482691cf24e1b8f80a863c97c2268e358271692967adc5612933da28
-  data.tar.gz: b56270d6324127635290a906bb6d7361a8c9609ad071ea307b26dcd3b16489c073be909e744680b52a202ab99019c611d9a0112cf2b18fc180f8113fb3fcef5a
+  metadata.gz: 9310e8b52be98d9087de88b4b7f5d105896edd85137c2f43e6c968c8daaf00dc6b4843ff9d1f228a089dcd7ceb379715c2b640d3c547ce173659dc7130cd1768
+  data.tar.gz: 65bade2024691c9c7527f6249294d01714563ff35c211472e6d984e82ba5acd0767251d33e05d8ade4208eabc8b1326eb47fc4f932b4699bf0b986e208fffcea

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-01-26
+
+### Fixed
+- Improve progress display accuracy for section candidates ([#136](https://github.com/ahogappa/taski/pull/136))
+
+### Changed
+- Extract helper methods for improved readability ([#136](https://github.com/ahogappa/taski/pull/136))
+
+## [0.8.2] - 2026-01-26
+
+### Fixed
+- Queue `Taski.message` output until progress display stops to prevent interleaved output ([#133](https://github.com/ahogappa/taski/pull/133))
+- Correct task count display in SimpleProgressDisplay ([#132](https://github.com/ahogappa/taski/pull/132))
+
+### Changed
+- Consolidate examples from 15 to 8 files for better maintainability ([#131](https://github.com/ahogappa/taski/pull/131))
+
 ## [0.8.1] - 2026-01-26
 
 ### Added

data/README.md

@@ -262,6 +262,34 @@ end
 
 When `TaskAbortException` is raised, no new tasks will start. Already running tasks will complete, then execution stops.
 
+### Lifecycle Management
+
+Define `clean` methods for resource cleanup. Clean runs in reverse dependency order:
+
+```ruby
+class DatabaseSetup < Taski::Task
+  exports :connection
+
+  def run
+    @connection = connect_to_database
+  end
+
+  def clean
+    @connection&.close
+  end
+end
+
+# Run then clean in one call
+DatabaseSetup.run_and_clean
+
+# Or separately
+DatabaseSetup.run
+# ... do work ...
+DatabaseSetup.clean
+```
+
+See [docs/guide.md](docs/guide.md#lifecycle-management) for details.
+
 ### Progress Display
 
 Tree-based progress visualization is enabled by default:
@@ -281,14 +309,27 @@ WebServer (Task)
 ✓ [5/5] All tasks completed (1234ms)
 ```
 
+**Plain mode** provides text output without escape codes (for CI/logs):
+
+```
+[START] DatabaseSetup
+[DONE] DatabaseSetup (45.2ms)
+[START] WebServer
+[DONE] WebServer (120.5ms)
+[TASKI] Completed: 2/2 tasks (165ms)
+```
+
 **Configuration:**
 
 ```ruby
 # Via API
-Taski.progress_mode = :simple  # or :tree (default)
+Taski.progress_mode = :tree    # Tree display (default)
+Taski.progress_mode = :simple  # Single-line display
+Taski.progress_mode = :plain   # Plain text (CI/logs)
 
 # Via environment variable
 TASKI_PROGRESS_MODE=simple ruby your_script.rb
+TASKI_PROGRESS_MODE=plain ruby your_script.rb
 ```
 
 To disable: `TASKI_PROGRESS_DISABLE=1 ruby your_script.rb`

data/docs/GUIDE.md

@@ -324,20 +324,34 @@ On failure:
 ✗ [3/5] DeployTask failed: Connection refused
 ```
 
+#### Plain Mode
+
+Plain text output without escape codes, designed for CI/logs:
+
+```
+[START] DatabaseSetup
+[DONE] DatabaseSetup (45.2ms)
+[START] WebServer
+[DONE] WebServer (120.5ms)
+[TASKI] Completed: 2/2 tasks (165ms)
+```
+
 ### Configuring Progress Mode
 
 **Via API:**
 
 ```ruby
-Taski.progress_mode = :simple  # Use simple mode
-Taski.progress_mode = :tree    # Use tree mode (default)
+Taski.progress_mode = :tree    # Tree display (default)
+Taski.progress_mode = :simple  # Single-line display
+Taski.progress_mode = :plain   # Plain text (CI/logs)
 ```
 
 **Via environment variable:**
 
 ```bash
-TASKI_PROGRESS_MODE=simple ruby your_script.rb
 TASKI_PROGRESS_MODE=tree ruby your_script.rb
+TASKI_PROGRESS_MODE=simple ruby your_script.rb
+TASKI_PROGRESS_MODE=plain ruby your_script.rb
 ```
 
 ### Disabling Progress Display
@@ -363,7 +377,7 @@ ruby build.rb > build.log 2>&1
 | Variable | Purpose |
 |----------|---------|
 | `TASKI_PROGRESS_DISABLE=1` | Disable progress display |
-| `TASKI_PROGRESS_MODE=simple\|tree` | Set progress display mode (default: tree) |
+| `TASKI_PROGRESS_MODE=tree\|simple\|plain` | Set progress display mode (default: tree) |
 | `TASKI_DEBUG=1` | Enable debug output |
 
 ### Dependency Tree Visualization

data/examples/README.md

@@ -67,78 +67,67 @@ TASKI_PROGRESS_DISABLE=1 ruby examples/reexecution_demo.rb
 
 ---
 
-### 5. data_pipeline_demo.rb - Real-World Pipeline
+### 5. clean_demo.rb - Lifecycle Management
 
-A realistic ETL pipeline with parallel data fetching.
-
-```bash
-ruby examples/data_pipeline_demo.rb
-```
-
-**Covers:**
-- Multiple data sources in parallel
-- Data transformation stages
-- Aggregation and reporting
-
----
-
-### 6. parallel_progress_demo.rb - Progress Display
-
-Real-time progress visualization during parallel execution.
+Demonstrates resource cleanup with clean methods.
 
 ```bash
-ruby examples/parallel_progress_demo.rb
+ruby examples/clean_demo.rb
 ```
 
 **Covers:**
-- Parallel task execution
-- Progress display with spinners
-- Execution timing
+- Defining `clean` methods for resource cleanup
+- Reverse dependency order execution
+- `run_and_clean` combined operation
 
 ---
 
-### 7. clean_demo.rb - Lifecycle Management
+### 6. group_demo.rb - Task Output Grouping
 
-Demonstrates resource cleanup with clean methods.
+Organize task output into logical phases with groups.
 
 ```bash
-ruby examples/clean_demo.rb
+ruby examples/group_demo.rb
 ```
 
 **Covers:**
-- Defining `clean` methods for resource cleanup
-- Reverse dependency order execution
-- `run_and_clean` combined operation
+- `group("label") { ... }` for organizing output
+- Groups displayed as children in progress tree
+- Multiple groups within a single task
 
 ---
 
-### 8. system_call_demo.rb - Subprocess Output
+### 7. message_demo.rb - User-Facing Messages
 
-Capture subprocess output in progress display.
+Output messages that bypass the progress display capture.
 
 ```bash
-ruby examples/system_call_demo.rb
+ruby examples/message_demo.rb
 ```
 
 **Covers:**
-- `system()` output capture
-- Streaming output display
-- Parallel subprocess execution
+- `Taski.message(text)` for user-facing output
+- Messages queued during progress and shown after completion
+- Difference between `puts` (captured) and `Taski.message` (bypassed)
 
 ---
 
-### 9. nested_section_demo.rb - Nested Sections
+### 8. progress_demo.rb - Progress Display Modes
 
-Sections that depend on other tasks for implementation selection.
+Real-time progress visualization during parallel execution.
 
 ```bash
-TASKI_PROGRESS_DISABLE=1 ruby examples/nested_section_demo.rb
+ruby examples/progress_demo.rb                              # Tree mode
+TASKI_PROGRESS_MODE=simple ruby examples/progress_demo.rb   # Simple mode
+TASKI_PROGRESS_DISABLE=1 ruby examples/progress_demo.rb     # Disabled
 ```
 
 **Covers:**
-- Section inside Section
-- Dynamic implementation selection
-- Complex dependency hierarchies
+- Tree progress display (default)
+- Simple one-line progress display
+- Parallel task execution
+- Task output capture and streaming
+- system() output integration
 
 ---
 
@@ -148,13 +137,12 @@ TASKI_PROGRESS_DISABLE=1 ruby examples/nested_section_demo.rb
 |---------|---------|------------|
 | quick_start | Exports API | Basic |
 | section_demo | Section API | Intermediate |
-| args_demo | Args API | Intermediate |
+| args_demo | Args/Env 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 |
+| group_demo | Output Grouping | Intermediate |
+| message_demo | User Messages | Basic |
+| progress_demo | Progress Display | Advanced |
 
 ## Running All Examples
 
@@ -163,7 +151,7 @@ TASKI_PROGRESS_DISABLE=1 ruby examples/nested_section_demo.rb
 for f in examples/*.rb; do echo "=== $f ===" && ruby "$f" && echo; done
 
 # Disable progress display if needed
-TASKI_PROGRESS_DISABLE=1 ruby examples/parallel_progress_demo.rb
+TASKI_PROGRESS_DISABLE=1 ruby examples/progress_demo.rb
 ```
 
 ## Next Steps

data/examples/progress_demo.rb

@@ -0,0 +1,154 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Progress Display Demo
+#
+# This example demonstrates the progress display modes:
+# - Tree mode (default): Shows task hierarchy with real-time updates
+# - Simple mode: One-line spinner with current task name
+#
+# Run:
+#   ruby examples/progress_demo.rb              # Tree mode (default)
+#   TASKI_PROGRESS_MODE=simple ruby examples/progress_demo.rb  # Simple mode
+#   TASKI_PROGRESS_DISABLE=1 ruby examples/progress_demo.rb    # No progress
+#
+# Covers:
+# - Parallel task execution with progress display
+# - Tree vs simple progress modes
+# - Task output capture and display
+# - system() output streaming
+
+require_relative "../lib/taski"
+
+# Configuration section with multiple implementations
+class DatabaseSection < Taski::Section
+  interfaces :connection_string
+
+  def impl
+    (ENV["USE_PROD_DB"] == "1") ? ProductionDB : DevelopmentDB
+  end
+
+  class ProductionDB < Taski::Task
+    def run
+      puts "Connecting to production database..."
+      sleep(0.4)
+      @connection_string = "postgresql://prod-server:5432/myapp"
+    end
+  end
+
+  class DevelopmentDB < Taski::Task
+    def run
+      puts "Connecting to development database..."
+      sleep(0.3)
+      @connection_string = "postgresql://localhost:5432/myapp_dev"
+    end
+  end
+end
+
+# Parallel download tasks (executed concurrently)
+class DownloadLayer1 < Taski::Task
+  exports :layer1_data
+
+  def run
+    puts "Downloading base image..."
+    sleep(0.8)
+    puts "Base image complete"
+    @layer1_data = "Layer 1 (base)"
+  end
+end
+
+class DownloadLayer2 < Taski::Task
+  exports :layer2_data
+
+  def run
+    puts "Downloading dependencies..."
+    sleep(1.2)
+    puts "Dependencies complete"
+    @layer2_data = "Layer 2 (deps)"
+  end
+end
+
+class DownloadLayer3 < Taski::Task
+  exports :layer3_data
+
+  def run
+    puts "Downloading application..."
+    sleep(0.4)
+    puts "Application complete"
+    @layer3_data = "Layer 3 (app)"
+  end
+end
+
+# Task that depends on all downloads (waits for parallel completion)
+class ExtractLayers < Taski::Task
+  exports :extracted_data
+
+  def run
+    layer1 = DownloadLayer1.layer1_data
+    layer2 = DownloadLayer2.layer2_data
+    layer3 = DownloadLayer3.layer3_data
+
+    puts "Extracting layers..."
+    sleep(0.3)
+    @extracted_data = [layer1, layer2, layer3]
+  end
+end
+
+# Task demonstrating system() output capture
+class RunSystemCommand < Taski::Task
+  exports :command_result
+
+  def run
+    puts "Running system command..."
+    @command_result = system("echo 'Step 1: Preparing...' && sleep 0.2 && echo 'Step 2: Processing...' && sleep 0.2 && echo 'Step 3: Done'")
+  end
+end
+
+# Final task combining all dependencies
+class BuildApplication < Taski::Task
+  exports :result
+
+  def run
+    db = DatabaseSection.connection_string
+    layers = ExtractLayers.extracted_data
+    RunSystemCommand.command_result
+
+    puts "Building application..."
+    sleep(0.3)
+    puts "Finalizing build..."
+    sleep(0.2)
+
+    @result = {
+      database: db,
+      layers: layers,
+      status: "success"
+    }
+  end
+end
+
+# Main execution
+puts "Taski Progress Display Demo"
+puts "=" * 50
+puts "Progress mode: #{Taski.progress_mode || "tree (default)"}"
+puts
+
+puts "Task Tree Structure:"
+puts "-" * 50
+puts BuildApplication.tree
+puts "-" * 50
+puts
+
+# Reset for fresh execution
+BuildApplication.reset!
+
+# Execute (progress display is automatic)
+result = BuildApplication.result
+
+puts
+puts "=" * 50
+puts "Execution completed!"
+puts "Result: #{result.inspect}"
+puts
+puts "Try different modes:"
+puts "  TASKI_PROGRESS_MODE=simple ruby examples/progress_demo.rb"
+puts "  TASKI_PROGRESS_DISABLE=1 ruby examples/progress_demo.rb"

data/lib/taski/execution/base_progress_display.rb

@@ -85,6 +85,7 @@ module Taski
         @root_task_class = nil
         @output_capture = nil
         @start_time = nil
+        @message_queue = []
       end
 
       # Set the output capture for getting task output
@@ -199,6 +200,14 @@ module Taski
         return unless should_stop
 
         on_stop
+        flush_queued_messages
+      end
+
+      # Queue a message to be displayed after progress display stops.
+      # Thread-safe for concurrent task execution.
+      # @param text [String] The message text to queue
+      def queue_message(text)
+        @monitor.synchronize { @message_queue << text }
       end
 
       protected
@@ -281,15 +290,47 @@ module Taski
         @output.tty?
       end
 
+      # Collect all dependencies of a task class recursively
+      # Useful for determining which tasks are needed by a selected implementation
+      # @param task_class [Class] The task class to collect dependencies for
+      # @return [Set<Class>] Set of all dependency task classes (including the task itself)
+      def collect_all_dependencies(task_class)
+        deps = Set.new
+        collect_dependencies_recursive(task_class, deps)
+        deps
+      end
+
       private
 
+      # Recursively collect dependencies into the given set
+      # @param task_class [Class] The task class
+      # @param collected [Set<Class>] Accumulated dependencies
+      def collect_dependencies_recursive(task_class, collected)
+        return if collected.include?(task_class)
+        collected.add(task_class)
+
+        task_class.cached_dependencies.each do |dep|
+          collect_dependencies_recursive(dep, collected)
+        end
+      end
+
+      # Flush all queued messages to output.
+      # Called when progress display stops.
+      def flush_queued_messages
+        messages = @monitor.synchronize { @message_queue.dup.tap { @message_queue.clear } }
+        messages.each { |msg| @output.puts(msg) }
+      end
+
       # Apply state transition to TaskProgress
+      # Note: Once a task reaches :completed or :failed, it cannot go back to :running.
+      # This prevents progress count from decreasing when nested executors re-execute tasks.
       def apply_state_transition(progress, state, duration, error)
         case state
         # Run lifecycle states
         when :pending
           progress.run_state = :pending
         when :running
+          return if run_state_finalized?(progress)
           progress.run_state = :running
           progress.run_start_time = Time.now
         when :completed
@@ -315,6 +356,10 @@ module Taski
         end
       end
 
+      def run_state_finalized?(progress)
+        progress.run_state == :completed || progress.run_state == :failed
+      end
+
       # Apply state transition to GroupProgress
       def apply_group_state_transition(progress, group_name, state, duration, error)
         case state

data/lib/taski/execution/execution_context.rb

@@ -81,7 +81,6 @@ module Taski
         @output_capture = nil
         @original_stdout = nil
         @runtime_dependencies = {}
-        @message_queue = []
       end
 
       # Check if output capture is already active.
@@ -90,23 +89,6 @@ module Taski
         @monitor.synchronize { !@output_capture.nil? }
       end
 
-      # Queue a message to be displayed after execution completes.
-      # Thread-safe for access from worker threads.
-      #
-      # @param text [String] The message text to queue
-      def queue_message(text)
-        @monitor.synchronize { @message_queue << text }
-      end
-
-      # Flush all queued messages to the given output.
-      # Clears the queue after flushing.
-      #
-      # @param output [IO] The output stream to write messages to
-      def flush_messages(output)
-        messages = @monitor.synchronize { @message_queue.dup.tap { @message_queue.clear } }
-        messages.each { |msg| output.puts(msg) }
-      end
-
       # Get the original stdout before output capture was set up.
       # Thread-safe accessor.
       #
@@ -123,7 +105,7 @@ module Taski
       def setup_output_capture(output_io)
         @monitor.synchronize do
           @original_stdout = output_io
-          @output_capture = TaskOutputRouter.new(@original_stdout)
+          @output_capture = TaskOutputRouter.new(@original_stdout, self)
           @output_capture.start_polling
           $stdout = @output_capture
         end
@@ -321,8 +303,7 @@ module Taski
         dispatch(:start)
       end
 
-      ##
-      # Notify registered observers that execution has stopped.
+      # Notify observers to stop.
       def notify_stop
         dispatch(:stop)
       end

data/lib/taski/execution/executor.rb

@@ -418,17 +418,9 @@ module Taski
       ensure
         stop_progress_display
         @saved_output_capture = @execution_context.output_capture
-        flush_queued_messages if should_teardown_capture
         teardown_output_capture if should_teardown_capture
       end
 
-      # Flush queued messages from ExecutionContext to original stdout.
-      # Called after progress display stops to show user messages.
-      def flush_queued_messages
-        output = @execution_context.original_stdout || $stdout
-        @execution_context.flush_messages(output)
-      end
-
       def create_default_execution_context
         context = ExecutionContext.new
         progress = Taski.progress_display