taski 0.5.0 → 0.7.1

data/lib/taski/execution/task_output_router.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "task_output_pipe"
+
+module Taski
+  module Execution
+    # Central coordinator that manages all task pipes and polling.
+    # Also acts as an IO proxy for $stdout, routing writes to the appropriate pipe
+    # based on the current thread.
+    #
+    # Architecture:
+    # - Each task gets a dedicated IO pipe for output capture
+    # - Writes are routed to the appropriate pipe based on Thread.current
+    # - A reader thread polls all pipes using IO.select for efficiency
+    # - When no pipe is registered for a thread, output goes to original stdout
+    class TaskOutputRouter
+      include MonitorMixin
+
+      POLL_TIMEOUT = 0.05 # 50ms timeout for IO.select
+      POLL_INTERVAL = 0.1 # 100ms between polls (matches TreeProgressDisplay)
+      READ_BUFFER_SIZE = 4096
+      MAX_RECENT_LINES = 30 # Maximum number of recent lines to keep per task
+
+      def initialize(original_stdout)
+        super()
+        @original = original_stdout
+        @pipes = {}         # task_class => TaskOutputPipe
+        @thread_map = {}    # Thread => task_class
+        @recent_lines = {}  # task_class => Array<String>
+        @poll_thread = nil
+        @polling = false
+      end
+
+      # Start the background polling thread
+      # This ensures pipes are drained even when display doesn't poll
+      def start_polling
+        synchronize do
+          return if @polling
+          @polling = true
+        end
+
+        @poll_thread = Thread.new do
+          loop do
+            break unless @polling
+            poll
+            sleep POLL_INTERVAL
+          end
+        end
+      end
+
+      # Stop the background polling thread
+      def stop_polling
+        synchronize { @polling = false }
+        @poll_thread&.join(0.5)
+        @poll_thread = nil
+      end
+
+      # Start capturing output for the current thread
+      # Creates a new pipe for the task and registers the thread mapping
+      # @param task_class [Class] The task class being executed
+      def start_capture(task_class)
+        synchronize do
+          pipe = TaskOutputPipe.new(task_class)
+          @pipes[task_class] = pipe
+          @thread_map[Thread.current] = task_class
+          debug_log("Started capture for #{task_class} on thread #{Thread.current.object_id}")
+        end
+      end
+
+      # Stop capturing output for the current thread
+      # Closes the write end of the pipe and drains remaining data
+      def stop_capture
+        task_class = nil
+        pipe = nil
+
+        synchronize do
+          task_class = @thread_map.delete(Thread.current)
+          unless task_class
+            debug_log("Warning: stop_capture called for unregistered thread #{Thread.current.object_id}")
+            return
+          end
+
+          pipe = @pipes[task_class]
+          pipe&.close_write
+          debug_log("Stopped capture for #{task_class} on thread #{Thread.current.object_id}")
+        end
+
+        # Drain any remaining data from the pipe after closing write end
+        drain_pipe(pipe) if pipe
+      end
+
+      # Drain all remaining data from a pipe
+      # Called after close_write to ensure all output is captured
+      def drain_pipe(pipe)
+        return if pipe.read_closed?
+
+        loop do
+          data = pipe.read_io.read_nonblock(READ_BUFFER_SIZE)
+          debug_log("drain_pipe read #{data.bytesize} bytes for #{pipe.task_class}")
+          store_output_lines(pipe.task_class, data)
+        rescue IO::WaitReadable
+          # Check if there's more data with a very short timeout
+          ready, = IO.select([pipe.read_io], nil, nil, 0.001)
+          break unless ready
+        rescue IOError
+          # All data has been read (EOFError) or pipe was closed by another thread
+          synchronize { pipe.close_read }
+          break
+        end
+      end
+
+      # Poll all open pipes for available data
+      # Should be called periodically from the display thread
+      def poll
+        readable_pipes = synchronize do
+          @pipes.values.reject { |p| p.read_closed? }.map(&:read_io)
+        end
+        return if readable_pipes.empty?
+
+        # Handle race condition: pipe may be closed between check and select
+        ready, = IO.select(readable_pipes, nil, nil, POLL_TIMEOUT)
+        return unless ready
+
+        ready.each do |read_io|
+          pipe = synchronize { @pipes.values.find { |p| p.read_io == read_io } }
+          next unless pipe
+
+          read_from_pipe(pipe)
+        end
+      rescue IOError
+        # Pipe was closed by another thread (drain_pipe), ignore
+      end
+
+      # Get the last output line for a task
+      # @param task_class [Class] The task class
+      # @return [String, nil] The last output line
+      def last_line_for(task_class)
+        synchronize { @recent_lines[task_class]&.last }
+      end
+
+      # Get recent output lines for a task (up to MAX_RECENT_LINES)
+      # @param task_class [Class] The task class
+      # @return [Array<String>] Recent output lines
+      def recent_lines_for(task_class)
+        synchronize { (@recent_lines[task_class] || []).dup }
+      end
+
+      # Close all pipes and clean up
+      def close_all
+        synchronize do
+          @pipes.each_value(&:close)
+          @pipes.clear
+          @thread_map.clear
+        end
+      end
+
+      # Check if there are any active (not fully closed) pipes
+      # @return [Boolean] true if there are active pipes
+      def active?
+        synchronize do
+          @pipes.values.any? { |p| !p.read_closed? }
+        end
+      end
+
+      # IO interface methods - route to pipe when capturing, otherwise pass through
+
+      def write(str)
+        pipe = current_thread_pipe
+        if pipe && !pipe.write_closed?
+          begin
+            pipe.write_io.write(str)
+          rescue IOError
+            # Pipe was closed by another thread (e.g., stop_capture), fall back to original
+            @original.write(str)
+          end
+        else
+          @original.write(str)
+        end
+      end
+
+      def puts(*args)
+        if args.empty?
+          write("\n")
+        else
+          args.each do |arg|
+            str = arg.to_s
+            write(str)
+            write("\n") unless str.end_with?("\n")
+          end
+        end
+        nil
+      end
+
+      def print(*args)
+        args.each { |arg| write(arg.to_s) }
+        nil
+      end
+
+      def <<(str)
+        write(str.to_s)
+        self
+      end
+
+      def flush
+        @original.flush
+      end
+
+      def tty?
+        @original.tty?
+      end
+
+      def isatty
+        @original.isatty
+      end
+
+      def winsize
+        @original.winsize
+      end
+
+      # Get the write IO for the current thread's pipe
+      # Used by Task#system to redirect subprocess output directly to the pipe
+      # @return [IO, nil] The write IO or nil if not capturing
+      def current_write_io
+        synchronize do
+          task_class = @thread_map[Thread.current]
+          return nil unless task_class
+          pipe = @pipes[task_class]
+          return nil if pipe.nil? || pipe.write_closed?
+          pipe.write_io
+        end
+      end
+
+      # Delegate unknown methods to original stdout
+      def method_missing(method, ...)
+        @original.send(method, ...)
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @original.respond_to?(method, include_private)
+      end
+
+      private
+
+      def current_thread_pipe
+        synchronize do
+          task_class = @thread_map[Thread.current]
+          return nil unless task_class
+          @pipes[task_class]
+        end
+      end
+
+      def read_from_pipe(pipe)
+        data = pipe.read_io.read_nonblock(READ_BUFFER_SIZE)
+        store_output_lines(pipe.task_class, data)
+      rescue IO::WaitReadable
+        # No data available yet
+      rescue IOError
+        # Pipe closed by writer (EOFError) or by another thread, close read end
+        synchronize { pipe.close_read }
+      end
+
+      def store_output_lines(task_class, data)
+        return if data.nil? || data.empty?
+
+        lines = data.lines
+        synchronize do
+          @recent_lines[task_class] ||= []
+          lines.each do |line|
+            stripped = line.chomp
+            @recent_lines[task_class] << stripped unless stripped.strip.empty?
+          end
+          # Keep only the last MAX_RECENT_LINES
+          if @recent_lines[task_class].size > MAX_RECENT_LINES
+            @recent_lines[task_class] = @recent_lines[task_class].last(MAX_RECENT_LINES)
+          end
+          debug_log("store_output_lines: #{task_class} now has #{@recent_lines[task_class].size} lines")
+        end
+      end
+
+      def debug_log(message)
+        return unless ENV["TASKI_DEBUG"]
+        warn "[TaskOutputRouter] #{message}"
+      end
+    end
+  end
+end

data/lib/taski/execution/task_wrapper.rb

@@ -26,24 +26,33 @@ module Taski
     # In the Producer-Consumer pattern, TaskWrapper does NOT start threads.
     # The Executor controls all scheduling and execution.
     class TaskWrapper
-      attr_reader :task, :result, :error, :timing
+      attr_reader :task, :result, :error, :timing, :clean_error
 
       STATE_PENDING = :pending
       STATE_RUNNING = :running
       STATE_COMPLETED = :completed
 
-      def initialize(task, registry:)
+      ##
+      # Create a new TaskWrapper for the given task and registry.
+      # Initializes synchronization primitives, state tracking for execution and cleanup, and timing/result/error holders.
+      # @param [Object] task - The task instance being wrapped.
+      # @param [Object] registry - The registry used to query abort status and coordinate execution.
+      # @param [Object, nil] execution_context - Optional execution context used to trigger and report execution and cleanup.
+      def initialize(task, registry:, execution_context: nil)
         @task = task
         @registry = registry
+        @execution_context = execution_context
         @result = nil
         @clean_result = nil
         @error = nil
+        @clean_error = nil
         @monitor = Monitor.new
         @condition = @monitor.new_cond
         @clean_condition = @monitor.new_cond
         @state = STATE_PENDING
         @clean_state = STATE_PENDING
         @timing = nil
+        @clean_timing = nil
       end
 
       # @return [Symbol] Current state
@@ -61,28 +70,67 @@ module Taski
         state == STATE_COMPLETED
       end
 
+      # Resets the wrapper state to allow re-execution.
+      # Clears all cached results and returns state to pending.
+      def reset!
+        @monitor.synchronize do
+          @state = STATE_PENDING
+          @clean_state = STATE_PENDING
+          @result = nil
+          @clean_result = nil
+          @error = nil
+          @clean_error = nil
+          @timing = nil
+          @clean_timing = nil
+        end
+        @task.reset! if @task.respond_to?(:reset!)
+        @registry.reset!
+      end
+
       # Called by user code to get result. Triggers execution if needed.
+      # Sets up args if not already set (for Task.new.run usage).
       # @return [Object] The result of task execution
       def run
-        trigger_execution_and_wait
-        raise @error if @error # steep:ignore
-        @result
+        with_args_lifecycle do
+          trigger_execution_and_wait
+          raise @error if @error # steep:ignore
+          @result
+        end
       end
 
       # Called by user code to clean. Triggers clean execution if needed.
+      # Sets up args if not already set (for Task.new.clean usage).
       # @return [Object] The result of cleanup
       def clean
-        trigger_clean_and_wait
-        @clean_result
+        with_args_lifecycle do
+          trigger_clean_and_wait
+          @clean_result
+        end
+      end
+
+      # Called by user code to run and clean. Runs execution followed by cleanup.
+      # If run fails, clean is still executed for resource release.
+      # Pre-increments progress display nest_level to prevent double rendering.
+      # @return [Object] The result of task execution
+      def run_and_clean
+        context = ensure_execution_context
+        context.notify_start # Pre-increment nest_level to prevent double rendering
+        run
+      ensure
+        clean
+        context&.notify_stop # Final decrement and render
       end
 
       # Called by user code to get exported value. Triggers execution if needed.
+      # Sets up args if not already set (for Task.new usage).
       # @param method_name [Symbol] The name of the exported method
       # @return [Object] The exported value
       def get_exported_value(method_name)
-        trigger_execution_and_wait
-        raise @error if @error # steep:ignore
-        @task.public_send(method_name)
+        with_args_lifecycle do
+          trigger_execution_and_wait
+          raise @error if @error # steep:ignore
+          @task.public_send(method_name)
+        end
       end
 
       # Called by Executor to mark task as running
@@ -108,7 +156,10 @@ module Taski
       end
 
       # Called by Executor when task.run raises an error
-      # @param error [Exception] The error that occurred
+      ##
+      # Marks the task as failed and records the error.
+      # Records the provided error, sets the task state to completed, updates the timing end time, notifies threads waiting for completion, and reports the failure to the execution context.
+      # @param [Exception] error - The exception raised during task execution.
       def mark_failed(error)
         @timing = @timing&.with_end_now
         @monitor.synchronize do
@@ -119,30 +170,75 @@ module Taski
         update_progress(:failed, error: error)
       end
 
+      # Called by Executor to mark clean as running
+      ##
+      # Mark the task's cleanup state as running and start timing.
+      # @return [Boolean] `true` if the clean state was changed from pending to running, `false` otherwise.
+      def mark_clean_running
+        @monitor.synchronize do
+          return false unless @clean_state == STATE_PENDING
+          @clean_state = STATE_RUNNING
+          @clean_timing = TaskTiming.start_now
+          true
+        end
+      end
+
       # Called by Executor after clean completes
-      # @param result [Object] The result of cleanup
+      ##
+      # Marks the cleanup run as completed, stores the cleanup result, sets the clean state to COMPLETED,
+      # notifies any waiters, and reports completion to observers.
+      # @param [Object] result - The result of the cleanup operation.
       def mark_clean_completed(result)
+        @clean_timing = @clean_timing&.with_end_now
         @monitor.synchronize do
           @clean_result = result
           @clean_state = STATE_COMPLETED
           @clean_condition.broadcast
         end
+        update_clean_progress(:clean_completed, duration: @clean_timing&.duration_ms)
+      end
+
+      # Called by Executor when clean raises an error
+      ##
+      # Marks the cleanup as failed by storing the cleanup error, transitioning the cleanup state to completed,
+      # notifying any waiters, and reports failure to observers.
+      # @param [Exception] error - The exception raised during the cleanup run.
+      def mark_clean_failed(error)
+        @clean_timing = @clean_timing&.with_end_now
+        @monitor.synchronize do
+          @clean_error = error
+          @clean_state = STATE_COMPLETED
+          @clean_condition.broadcast
+        end
+        update_clean_progress(:clean_failed, duration: @clean_timing&.duration_ms, error: error)
       end
 
-      # Wait until task is completed
+      ##
+      # Blocks the current thread until the task reaches the completed state.
+      #
+      # The caller will be suspended until the wrapper's state becomes STATE_COMPLETED.
+      # This method does not raise on its own; any errors from task execution are surfaced elsewhere.
       def wait_for_completion
         @monitor.synchronize do
           @condition.wait_until { @state == STATE_COMPLETED }
         end
       end
 
-      # Wait until clean is completed
+      ##
+      # Blocks the current thread until the task's clean phase reaches the completed state.
+      # The caller will be suspended until the wrapper's clean_state becomes STATE_COMPLETED.
       def wait_for_clean_completion
         @monitor.synchronize do
           @clean_condition.wait_until { @clean_state == STATE_COMPLETED }
         end
       end
 
+      ##
+      # Delegates method calls to get_exported_value for exported task methods.
+      # @param method_name [Symbol] The method name being called.
+      # @param args [Array] Arguments passed to the method.
+      # @param block [Proc] Block passed to the method.
+      # @return [Object] The exported value for the method.
       def method_missing(method_name, *args, &block)
         if @task.class.method_defined?(method_name)
           get_exported_value(method_name)
@@ -151,22 +247,65 @@ module Taski
         end
       end
 
+      ##
+      # Returns true if the task class defines the given method.
+      # @param method_name [Symbol] The method name to check.
+      # @param include_private [Boolean] Whether to include private methods.
+      # @return [Boolean] true if the task responds to the method.
       def respond_to_missing?(method_name, include_private = false)
         @task.class.method_defined?(method_name) || super
       end
 
       private
 
-      # Trigger execution via Executor and wait for completion
+      ##
+      # Ensures args are set during block execution, then resets if they weren't set before.
+      # This allows Task.new.run usage without requiring explicit args setup.
+      # @yield The block to execute with args lifecycle management
+      # @return [Object] The result of the block
+      def with_args_lifecycle(&block)
+        Taski.with_args(options: {}, root_task: @task.class, &block)
+      end
+
+      ##
+      # Ensures the task is executed if still pending and waits for completion.
+      # If the task is pending, triggers execution (via the configured ExecutionContext when present, otherwise via Executor) outside the monitor; if the task is running, waits until it becomes completed; if already completed, returns immediately.
+      # @raise [Taski::TaskAbortException] If the registry requested an abort before execution begins.
       def trigger_execution_and_wait
+        trigger_and_wait(
+          state_accessor: -> { @state },
+          condition: @condition,
+          trigger: ->(ctx) { ctx.trigger_execution(@task.class, registry: @registry) }
+        )
+      end
+
+      ##
+      # Triggers task cleanup through the configured execution mechanism and waits until the cleanup completes.
+      #
+      # If an ExecutionContext is configured the cleanup is invoked through it; otherwise a fallback executor is used.
+      # @raise [Taski::TaskAbortException] if the registry has requested an abort.
+      def trigger_clean_and_wait
+        trigger_and_wait(
+          state_accessor: -> { @clean_state },
+          condition: @clean_condition,
+          trigger: ->(ctx) { ctx.trigger_clean(@task.class, registry: @registry) }
+        )
+      end
+
+      # Generic trigger-and-wait implementation for both run and clean phases.
+      # @param state_accessor [Proc] Lambda returning the current state
+      # @param condition [MonitorMixin::ConditionVariable] Condition to wait on
+      # @param trigger [Proc] Lambda receiving context to trigger execution
+      # @raise [Taski::TaskAbortException] If the registry requested an abort
+      def trigger_and_wait(state_accessor:, condition:, trigger:)
         should_execute = false
         @monitor.synchronize do
-          case @state
+          case state_accessor.call
           when STATE_PENDING
             check_abort!
             should_execute = true
           when STATE_RUNNING
-            @condition.wait_until { @state == STATE_COMPLETED }
+            condition.wait_until { state_accessor.call == STATE_COMPLETED }
           when STATE_COMPLETED
             # Already done
           end
@@ -174,57 +313,81 @@ module Taski
 
         if should_execute
           # Execute outside the lock to avoid deadlock
-          Executor.execute(@task.class, registry: @registry)
-          # After Executor.execute returns, the task is completed
+          context = ensure_execution_context
+          trigger.call(context)
+          # After execution returns, the task is completed
         end
       end
 
-      # Trigger clean execution and wait for completion
-      def trigger_clean_and_wait
-        @monitor.synchronize do
-          case @clean_state
-          when STATE_PENDING
-            @clean_state = STATE_RUNNING
-            # Execute clean in a thread (clean doesn't use Producer-Consumer)
-            thread = Thread.new { execute_clean }
-            @registry.register_thread(thread)
-            @clean_condition.wait_until { @clean_state == STATE_COMPLETED }
-          when STATE_RUNNING
-            @clean_condition.wait_until { @clean_state == STATE_COMPLETED }
-          when STATE_COMPLETED
-            # Already done
-          end
+      ##
+      # Checks whether the registry has requested an abort and raises an exception to stop starting new tasks.
+      # @raise [Taski::TaskAbortException] if `@registry.abort_requested?` is true — raised with the message "Execution aborted - no new tasks will start".
+      def check_abort!
+        if @registry.abort_requested?
+          raise Taski::TaskAbortException, "Execution aborted - no new tasks will start"
         end
       end
 
-      def execute_clean
-        debug_log("Cleaning #{@task.class}...")
-        result = @task.clean
-        wait_for_clean_dependencies
-        mark_clean_completed(result)
-        debug_log("Clean #{@task.class} completed.")
+      ##
+      # Ensures an execution context exists for this wrapper.
+      # Returns the existing context if set, otherwise creates a shared context.
+      # This enables run and clean phases to share state like runtime dependencies.
+      # @return [ExecutionContext] The execution context for this wrapper
+      def ensure_execution_context
+        @execution_context ||= create_shared_context
       end
 
-      def wait_for_clean_dependencies
-        dependencies = @task.class.cached_dependencies
-        return if dependencies.empty?
+      ##
+      # Creates a shared execution context with proper triggers for run and clean.
+      # The context is configured to reuse itself when triggering nested executions.
+      # @return [ExecutionContext] A new execution context
+      def create_shared_context
+        context = ExecutionContext.new
+        progress = Taski.progress_display
+        context.add_observer(progress) if progress
 
-        wait_threads = dependencies.map do |dep_class|
-          Thread.new { dep_class.clean }
+        # Set triggers to reuse this context for nested executions
+        context.execution_trigger = ->(task_class, registry) do
+          Executor.execute(task_class, registry: registry, execution_context: context)
         end
-        wait_threads.each(&:join)
-      end
-
-      def check_abort!
-        if @registry.abort_requested?
-          raise Taski::TaskAbortException, "Execution aborted - no new tasks will start"
+        context.clean_trigger = ->(task_class, registry) do
+          Executor.execute_clean(task_class, registry: registry, execution_context: context)
         end
+
+        context
       end
 
+      ##
+      # Notifies the execution context of task completion or failure.
+      # Falls back to getting the current context if not set during initialization.
+      # @param state [Symbol] The completion state (unused, kept for API consistency).
+      # @param duration [Numeric, nil] The execution duration in milliseconds.
+      # @param error [Exception, nil] The error if the task failed.
       def update_progress(state, duration: nil, error: nil)
-        Taski.progress_display&.update_task(@task.class, state: state, duration: duration, error: error)
+        # Defensive fallback: try to get current context if not set during initialization
+        @execution_context ||= ExecutionContext.current
+        return unless @execution_context
+
+        @execution_context.notify_task_completed(@task.class, duration: duration, error: error)
+      end
+
+      ##
+      # Notifies the execution context of clean completion or failure.
+      # Falls back to getting the current context if not set during initialization.
+      # @param state [Symbol] The clean state (unused, kept for API consistency).
+      # @param duration [Numeric, nil] The clean duration in milliseconds.
+      # @param error [Exception, nil] The error if the clean failed.
+      def update_clean_progress(state, duration: nil, error: nil)
+        # Defensive fallback: try to get current context if not set during initialization
+        @execution_context ||= ExecutionContext.current
+        return unless @execution_context
+
+        @execution_context.notify_clean_completed(@task.class, duration: duration, error: error)
       end
 
+      ##
+      # Outputs a debug message if TASKI_DEBUG environment variable is set.
+      # @param message [String] The debug message to output.
       def debug_log(message)
         return unless ENV["TASKI_DEBUG"]
         puts "[TaskWrapper] #{message}"