taski 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7677c0f3995a7c61b5850fb25c82c60626287584e5c7f918939ededc045e9ea
-  data.tar.gz: d470969c88a4df51503487aacdf2c6261b65e6ed75ee3c7cc2ff744dfd750365
+  metadata.gz: 1ecbd73a50d1f39207625cda94e9f90a90ce212d270a70ed49cd94705bb30a5c
+  data.tar.gz: d5efd7fcf8c5c0d5bdfacf147e302375e63d41acd00f428924e87ba3a4e54ac0
 SHA512:
-  metadata.gz: 5f93d9e7d10f7104851266f0252ec4365d445a90d3a25b885f289df5d8caafbe9f9250ff9236e4cca0791749100c83c46735a8e98e5c1b675662199ba7a0e547
-  data.tar.gz: eb4fb9f806cdd5097e0d3321d4cda9e3df183d4850c4aa8161ba09b71666444166f05b5e795b330227076d85f7410adbe2fc4f1e2b19c66d007ff1632d354f97
+  metadata.gz: e263e9c974f17ff46f545adc3cf90cddf66cbfe273c783d07f036a2d3fc4c7f8ec4759c1a94ff72ab0b302d8c4fae50a4654cda5b4b17d9f218ae897ba67572a
+  data.tar.gz: 9bf8d6b053ee781ef9ba2535926ef663be9ed45d88249d59a5325d7cbd600468ae5bacc69e506ae5bc7f2819707b9e4451a0faf0aa377dbbfb33fe04a7d9199b

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- `Taski.message` API for user-facing output during task execution ([#129](https://github.com/ahogappa/taski/pull/129))
+
+### Fixed
+- Count unselected section candidates as completed in SimpleProgressDisplay ([#128](https://github.com/ahogappa/taski/pull/128))
+- Prioritize environment variable over code settings for progress_mode ([#127](https://github.com/ahogappa/taski/pull/127))
+
 ## [0.8.0] - 2026-01-23
 
 ### 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/message_demo.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstrates Taski.message API
+#
+# Taski.message outputs text to the user without being captured by TaskOutputRouter.
+# Messages are queued during progress display and shown after task completion.
+#
+# Usage:
+#   ruby examples/message_demo.rb
+#   TASKI_FORCE_PROGRESS=1 ruby examples/message_demo.rb  # Force progress display
+
+require_relative "../lib/taski"
+
+class ProcessDataTask < Taski::Task
+  exports :processed_count
+
+  def run
+    puts "Starting data processing..."  # Captured by TaskOutputRouter
+
+    # Simulate processing
+    5.times do |i|
+      puts "Processing batch #{i + 1}/5..."  # Captured
+      sleep 0.3
+    end
+
+    @processed_count = 42
+
+    # These messages bypass TaskOutputRouter and appear after execution
+    Taski.message("Created: /tmp/output.txt")
+    Taski.message("Summary: #{@processed_count} items processed successfully")
+  end
+end
+
+class GenerateReportTask < Taski::Task
+  exports :report_path
+
+  def run
+    # Dependency: ProcessDataTask will be executed first
+    count = ProcessDataTask.processed_count
+    puts "Generating report for #{count} items..."  # Captured
+
+    sleep 0.5
+
+    @report_path = "/tmp/report.pdf"
+
+    Taski.message("Report available at: #{@report_path}")
+  end
+end
+
+puts "=== Taski.message Demo ==="
+puts
+
+GenerateReportTask.run
+
+puts
+puts "=== Done ==="

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
@@ -283,6 +292,13 @@ module Taski
 
       private
 
+      # 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
       def apply_state_transition(progress, state, duration, error)
         case state

data/lib/taski/execution/execution_context.rb

@@ -89,6 +89,14 @@ module Taski
         @monitor.synchronize { !@output_capture.nil? }
       end
 
+      # Get the original stdout before output capture was set up.
+      # Thread-safe accessor.
+      #
+      # @return [IO, nil] The original stdout or nil if not captured
+      def original_stdout
+        @monitor.synchronize { @original_stdout }
+      end
+
       # Set up output capture for inline progress display.
       # Creates TaskOutputRouter and replaces $stdout.
       # Should only be called when progress display is active and not already set up.
@@ -97,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
@@ -295,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/simple_progress_display.rb

@@ -34,6 +34,7 @@ module Taski
         @spinner_index = 0
         @renderer_thread = nil
         @running = false
+        @section_candidates = {} # section_class => [candidate_classes]
       end
 
       protected
@@ -44,9 +45,23 @@ module Taski
       end
 
       # Template method: Called when a section impl is registered
-      def on_section_impl_registered(_section_class, impl_class)
+      def on_section_impl_registered(section_class, impl_class)
         @tasks[impl_class] ||= TaskProgress.new
         @tasks[impl_class].is_impl_candidate = false
+
+        # Mark the section itself as completed (it's represented by its impl)
+        if @tasks[section_class]
+          @tasks[section_class].run_state = :completed
+        end
+
+        # Mark unselected candidates as completed (skipped)
+        candidates = @section_candidates[section_class] || []
+        candidates.each do |candidate|
+          next if candidate == impl_class
+          progress = @tasks[candidate]
+          next unless progress
+          progress.run_state = :completed
+        end
       end
 
       # Template method: Determine if display should activate
@@ -83,6 +98,23 @@ module Taski
         # Use TreeProgressDisplay's static method for tree building
         tree = TreeProgressDisplay.build_tree_node(@root_task_class)
         register_tasks_from_tree(tree)
+        collect_section_candidates(tree)
+      end
+
+      def collect_section_candidates(node)
+        return unless node
+
+        task_class = node[:task_class]
+
+        # If this is a section, collect its implementation candidates
+        if node[:is_section]
+          candidates = node[:children]
+            .select { |c| c[:is_impl_candidate] }
+            .map { |c| c[:task_class] }
+          @section_candidates[task_class] = candidates unless candidates.empty?
+        end
+
+        node[:children].each { |child| collect_section_candidates(child) }
       end
 
       def render_live
@@ -121,7 +153,8 @@ module Taski
       def build_status_line
         running_tasks = @tasks.select { |_, p| p.run_state == :running }
         cleaning_tasks = @tasks.select { |_, p| p.clean_state == :cleaning }
-        completed = @tasks.values.count { |p| p.run_state == :completed }
+        # Count both completed and failed tasks as "done"
+        done = @tasks.values.count { |p| p.run_state == :completed || p.run_state == :failed }
         failed = @tasks.values.count { |p| p.run_state == :failed }
         total = @tasks.size
 
@@ -147,7 +180,7 @@ module Taski
         # Get last output message if available
         output_suffix = build_output_suffix(running_tasks.keys.first || cleaning_tasks.keys.first)
 
-        parts = ["#{status_icon} [#{completed}/#{total}]"]
+        parts = ["#{status_icon} [#{done}/#{total}]"]
         parts << task_names if task_names && !task_names.empty?
         parts << "|" << output_suffix if output_suffix
 

data/lib/taski/execution/task_output_router.rb

@@ -22,9 +22,10 @@ module Taski
       READ_BUFFER_SIZE = 4096
       MAX_RECENT_LINES = 30 # Maximum number of recent lines to keep per task
 
-      def initialize(original_stdout)
+      def initialize(original_stdout, execution_context = nil)
         super()
         @original = original_stdout
+        @execution_context = execution_context
         @pipes = {}         # task_class => TaskOutputPipe
         @thread_map = {}    # Thread => task_class
         @recent_lines = {}  # task_class => Array<String>

data/lib/taski/version.rb

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