taski 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ca85800083318a5bc4d40151f14e5c55d6474a81a89a095de6d2433a8609043
-  data.tar.gz: d68b0a3f9bf5bab689882df7cdf22fe02a169008a3d4bd64a24eaea2699dce33
+  metadata.gz: f7677c0f3995a7c61b5850fb25c82c60626287584e5c7f918939ededc045e9ea
+  data.tar.gz: d470969c88a4df51503487aacdf2c6261b65e6ed75ee3c7cc2ff744dfd750365
 SHA512:
-  metadata.gz: 3705a29cdf6e5fbe4a244b9431c35bc326e2c383f71e00fe7223a1e87f98728e565e1faebbd081111ab8127197e39294c89d05c6e35511b8405425f21b6a8af3
-  data.tar.gz: 87d334c0e053bbd164c260e304f642a26305f14021de17bf10bb8d50180fd0160338efbca0821a3fc3af996b8212e3a10c52d5e533c54b6141b069e17f21af7a
+  metadata.gz: 5f93d9e7d10f7104851266f0252ec4365d445a90d3a25b885f289df5d8caafbe9f9250ff9236e4cca0791749100c83c46735a8e98e5c1b675662199ba7a0e547
+  data.tar.gz: eb4fb9f806cdd5097e0d3321d4cda9e3df183d4850c4aa8161ba09b71666444166f05b5e795b330227076d85f7410adbe2fc4f1e2b19c66d007ff1632d354f97

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-01-23
+
+### Added
+- `Taski::Env` class for system-managed execution environment information ([#125](https://github.com/ahogappa/taski/pull/125))
+  - Access via `Taski.env.working_directory`, `Taski.env.started_at`, `Taski.env.root_task`
+- `args` and `workers` parameters to `Task.new` for direct task instantiation ([#125](https://github.com/ahogappa/taski/pull/125))
+- `mock_env` helper in `TestHelper` for mocking environment in tests ([#125](https://github.com/ahogappa/taski/pull/125))
+
+### Changed
+- Separate system attributes from `Taski.args` to `Taski.env` ([#125](https://github.com/ahogappa/taski/pull/125))
+  - `Taski.args` now holds only user-defined options passed via `run(args: {...})`
+  - `Taski.env` holds system-managed execution environment (`root_task`, `started_at`, `working_directory`)
+
+## [0.7.1] - 2026-01-22
+
+### Added
+- `Taski::TestHelper` module for mocking task dependencies in unit tests ([#123](https://github.com/ahogappa/taski/pull/123))
+  - `mock_task(TaskClass, key: value)` to mock exported values without running tasks
+  - `assert_task_accessed` / `refute_task_accessed` for verifying dependency access
+  - Support for both Minitest and RSpec test frameworks
+- Simple one-line progress display mode (`Taski.progress_mode = :simple`) as an alternative to tree display ([#112](https://github.com/ahogappa/taski/pull/112))
+  - Configure via `TASKI_PROGRESS_MODE` environment variable or `Taski.progress_mode` API
+- Display captured task output (up to 30 lines) in AggregateError messages for better debugging ([#109](https://github.com/ahogappa/taski/pull/109))
+- Background polling thread in TaskOutputRouter to ensure pipes are drained reliably ([#122](https://github.com/ahogappa/taski/pull/122))
+- `Taski.with_args` helper method for safe argument lifecycle management ([#110](https://github.com/ahogappa/taski/pull/110))
+
+### Changed
+- Progress display now uses alternate screen buffer and shows summary line after completion ([#107](https://github.com/ahogappa/taski/pull/107))
+- Eliminate screen flickering in tree progress display with in-place overwrite rendering ([#121](https://github.com/ahogappa/taski/pull/121))
+- Extract `BaseProgressDisplay` class for shared progress display functionality ([#117](https://github.com/ahogappa/taski/pull/117))
+
+### Fixed
+- Wait for running dependencies in nested executor to prevent deadlock ([#106](https://github.com/ahogappa/taski/pull/106))
+- Preserve namespace path when following method calls in static analysis ([#108](https://github.com/ahogappa/taski/pull/108))
+- Prevent race condition in `Taski.args` lifecycle during concurrent execution ([#110](https://github.com/ahogappa/taski/pull/110))
+- Ensure progress display cleanup on interrupt (Ctrl+C) ([#107](https://github.com/ahogappa/taski/pull/107))
+- Always enable output in PlainProgressDisplay ([#117](https://github.com/ahogappa/taski/pull/117))
+
 ## [0.7.0] - 2025-12-23
 
 ### Added

data/README.md

@@ -203,14 +203,14 @@ Pass custom options and access execution context from any task:
 ```ruby
 class DeployTask < Taski::Task
   def run
-    # User-defined options
+    # User-defined options (Taski.args)
     env = Taski.args[:env]
     debug = Taski.args.fetch(:debug, false)
 
-    # Runtime information
-    puts "Working directory: #{Taski.args.working_directory}"
-    puts "Started at: #{Taski.args.started_at}"
-    puts "Root task: #{Taski.args.root_task}"
+    # Runtime environment information (Taski.env)
+    puts "Working directory: #{Taski.env.working_directory}"
+    puts "Started at: #{Taski.env.started_at}"
+    puts "Root task: #{Taski.env.root_task}"
     puts "Deploying to: #{env}"
   end
 end
@@ -219,13 +219,15 @@ end
 DeployTask.run(args: { env: "production", debug: true })
 ```
 
-Args API:
+Args API (user-defined options):
 - `Taski.args[:key]` - Get option value (nil if not set)
 - `Taski.args.fetch(:key, default)` - Get with default value
 - `Taski.args.key?(:key)` - Check if option exists
-- `Taski.args.working_directory` - Execution directory
-- `Taski.args.started_at` - Execution start time
-- `Taski.args.root_task` - First task class called
+
+Env API (execution environment):
+- `Taski.env.working_directory` - Execution directory
+- `Taski.env.started_at` - Execution start time
+- `Taski.env.root_task` - First task class called
 
 ### Execution Model
 

data/examples/README.md

@@ -46,9 +46,9 @@ ruby examples/args_demo.rb
 - User-defined options via `run(args: {...})`
 - `Taski.args[:key]` for option access
 - `Taski.args.fetch(:key, default)` for defaults
-- `Taski.args.working_directory`
-- `Taski.args.started_at`
-- `Taski.args.root_task`
+- `Taski.env.working_directory`
+- `Taski.env.started_at`
+- `Taski.env.root_task`
 
 ---
 

data/examples/args_demo.rb

@@ -1,35 +1,36 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Taski Args API Example
+# Taski Args & Env API Example
 #
-# This example demonstrates the Args API for accessing runtime information:
-# - working_directory: Where execution started
-# - started_at: When execution began
-# - root_task: The first task class that was called
-# - User-defined options: Custom values passed via run(args: {...})
+# This example demonstrates the Args and Env APIs:
+# - Taski.env: Execution environment information
+#   - working_directory: Where execution started
+#   - started_at: When execution began
+#   - root_task: The first task class that was called
+# - Taski.args: User-defined options passed via run(args: {...})
 #
 # Run: ruby examples/args_demo.rb
 
 require_relative "../lib/taski"
 
-puts "Taski Args API Example"
+puts "Taski Args & Env API Example"
 puts "=" * 40
 
-# Task that uses args information for logging
+# Task that uses env information for logging
 class SetupTask < Taski::Task
   exports :setup_info
 
   def run
     puts "Setup running..."
-    puts "  Working directory: #{Taski.args.working_directory}"
-    puts "  Started at: #{Taski.args.started_at}"
-    puts "  Root task: #{Taski.args.root_task}"
+    puts "  Working directory: #{Taski.env.working_directory}"
+    puts "  Started at: #{Taski.env.started_at}"
+    puts "  Root task: #{Taski.env.root_task}"
     puts "  Environment: #{Taski.args[:env]}"
 
     @setup_info = {
-      directory: Taski.args.working_directory,
-      timestamp: Taski.args.started_at,
+      directory: Taski.env.working_directory,
+      timestamp: Taski.env.started_at,
       env: Taski.args[:env]
     }
   end
@@ -40,8 +41,8 @@ class FileProcessor < Taski::Task
   exports :output_path
 
   def run
-    # Use args to determine output location
-    base_dir = Taski.args.working_directory
+    # Use env to determine output location
+    base_dir = Taski.env.working_directory
     env = Taski.args.fetch(:env, "development")
     @output_path = File.join(base_dir, "tmp", env, "output.txt")
 
@@ -55,7 +56,7 @@ class TimingTask < Taski::Task
   exports :duration_info
 
   def run
-    start_time = Taski.args.started_at
+    start_time = Taski.env.started_at
     current_time = Time.now
     elapsed = current_time - start_time
 
@@ -76,7 +77,7 @@ class MainTask < Taski::Task
 
   def run
     puts "\nMainTask executing..."
-    puts "  Root task is: #{Taski.args.root_task}"
+    puts "  Root task is: #{Taski.env.root_task}"
     puts "  Environment: #{Taski.args[:env]}"
 
     # Access dependencies
@@ -88,7 +89,7 @@ class MainTask < Taski::Task
       setup: setup,
       output_path: output,
       timing: timing,
-      root_task: Taski.args.root_task.to_s
+      root_task: Taski.env.root_task.to_s
     }
 
     puts "\nExecution Summary:"
@@ -114,5 +115,5 @@ puts "-" * 40
 puts MainTask.tree
 
 puts "\n" + "=" * 40
-puts "Args API demonstration complete!"
-puts "Note: Args provides runtime information and user options without affecting dependency analysis."
+puts "Args & Env API demonstration complete!"
+puts "Note: Args provides user options, Env provides execution environment info."

data/lib/taski/args.rb

@@ -4,18 +4,12 @@ require "monitor"
 
 module Taski
   # Runtime arguments accessible from any task.
-  # Holds user-defined options and execution metadata.
+  # Holds user-defined options passed by the user at execution time.
   # Args is immutable after creation - options cannot be modified during task execution.
   class Args
-    attr_reader :started_at, :working_directory, :root_task
-
     # @param options [Hash] User-defined options (immutable after creation)
-    # @param root_task [Class] The root task class that initiated execution
-    def initialize(options:, root_task:)
+    def initialize(options:)
       @options = options.dup.freeze
-      @root_task = root_task
-      @started_at = Time.now
-      @working_directory = Dir.pwd
     end
 
     # Get a user-defined option value

data/lib/taski/env.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Taski
+  # Runtime execution environment information.
+  # Holds system-managed metadata that is set automatically during task execution.
+  # Env is immutable after creation.
+  class Env
+    attr_reader :root_task, :started_at, :working_directory
+
+    # @param root_task [Class] The root task class that initiated execution
+    def initialize(root_task:)
+      @root_task = root_task
+      @started_at = Time.now
+      @working_directory = Dir.pwd
+    end
+  end
+end

data/lib/taski/execution/task_wrapper.rb

@@ -38,10 +38,12 @@ module Taski
       # @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)
+      # @param [Hash, nil] args - User-defined arguments for Task.new usage.
+      def initialize(task, registry:, execution_context: nil, args: nil)
         @task = task
         @registry = registry
         @execution_context = execution_context
+        @args = args
         @result = nil
         @clean_result = nil
         @error = nil
@@ -261,10 +263,18 @@ module Taski
       ##
       # 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.
+      # If args are already set (e.g., from Task.run class method), just yields the block.
+      # Uses stored @args if set (from Task.new), otherwise uses empty hash.
       # @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)
+        # If args are already set, just execute the block
+        return yield if Taski.args
+
+        options = @args || {}
+        Taski.send(:with_env, root_task: @task.class) do
+          Taski.send(:with_args, options: options, &block)
+        end
       end
 
       ##

data/lib/taski/task.rb

@@ -50,11 +50,24 @@ module Taski
       end
 
       ##
-      # Creates a fresh TaskWrapper instance for re-execution support.
-      # Use class methods (e.g., MyTask.result) for cached single execution.
+      # Creates a task instance for manual execution control.
+      # Use class methods (e.g., MyTask.run) for simple execution.
+      # @param args [Hash] User-defined arguments accessible via Taski.args.
+      # @param workers [Integer, nil] Number of worker threads for parallel execution.
       # @return [Execution::TaskWrapper] A new wrapper for this task.
-      def new
-        fresh_wrapper
+      def new(args: {}, workers: nil)
+        validate_workers!(workers)
+        fresh_registry = Execution::Registry.new
+        task_instance = allocate
+        task_instance.__send__(:initialize)
+        wrapper = Execution::TaskWrapper.new(
+          task_instance,
+          registry: fresh_registry,
+          execution_context: Execution::ExecutionContext.current,
+          args: args.merge(_workers: workers)
+        )
+        fresh_registry.register(self, wrapper)
+        wrapper
       end
 
       ##
@@ -138,9 +151,11 @@ module Taski
       # @return [Object] The result of the block
       def with_execution_setup(args:, workers:)
         validate_workers!(workers)
-        Taski.with_args(options: args.merge(_workers: workers), root_task: self) do
-          validate_no_circular_dependencies!
-          yield fresh_wrapper
+        Taski.send(:with_env, root_task: self) do
+          Taski.send(:with_args, options: args.merge(_workers: workers)) do
+            validate_no_circular_dependencies!
+            yield fresh_wrapper
+          end
         end
       end
 
@@ -199,9 +214,11 @@ module Taski
             wrapper.get_exported_value(method)
           else
             # Outside execution - fresh execution (top-level call)
-            Taski.with_args(options: {}, root_task: self) do
-              validate_no_circular_dependencies!
-              fresh_wrapper.get_exported_value(method)
+            Taski.send(:with_env, root_task: self) do
+              Taski.send(:with_args, options: {}) do
+                validate_no_circular_dependencies!
+                fresh_wrapper.get_exported_value(method)
+              end
             end
           end
         end

data/lib/taski/test_helper/mock_registry.rb

@@ -38,12 +38,14 @@ module Taski
           end
         end
 
-        # Clears all registered mocks.
+        # Clears all registered mocks and resets args/env.
         # Should be called in test setup/teardown.
         def reset!
           @mutex.synchronize do
             @mocks = {}
           end
+          Taski.reset_args!
+          Taski.reset_env!
         end
       end
     end

data/lib/taski/test_helper.rb

@@ -43,9 +43,11 @@ module Taski
             end
             wrapper.get_exported_value(method)
           else
-            Taski.with_args(options: {}, root_task: self) do
-              validate_no_circular_dependencies!
-              fresh_wrapper.get_exported_value(method)
+            Taski.send(:with_env, root_task: self) do
+              Taski.send(:with_args, options: {}) do
+                validate_no_circular_dependencies!
+                fresh_wrapper.get_exported_value(method)
+              end
             end
           end
         end
@@ -110,6 +112,36 @@ module Taski
       end
     end
 
+    # Sets mock args for the duration of the test.
+    # This allows testing code that depends on Taski.args without running full task execution.
+    # Args are automatically cleared when MockRegistry.reset! is called (in test teardown).
+    # @param options [Hash] User-defined options to include in args
+    # @return [Taski::Args] The created args instance
+    #
+    # @example
+    #   mock_args(env: "test", debug: true)
+    #   assert_equal "test", Taski.args[:env]
+    def mock_args(**options)
+      Taski.reset_args!
+      Taski.send(:start_args, options: options)
+      Taski.args
+    end
+
+    # Sets mock env for the duration of the test.
+    # This allows testing code that depends on Taski.env without running full task execution.
+    # Env is automatically cleared when MockRegistry.reset! is called (in test teardown).
+    # @param root_task [Class] The root task class (defaults to nil for testing)
+    # @return [Taski::Env] The created env instance
+    #
+    # @example
+    #   mock_env(root_task: MyTask)
+    #   assert_equal MyTask, Taski.env.root_task
+    def mock_env(root_task: nil)
+      Taski.reset_env!
+      Taski.send(:start_env, root_task: root_task)
+      Taski.env
+    end
+
     # Registers a mock for a task class with specified return values.
     # @param task_class [Class] A Taski::Task or Taski::Section subclass
     # @param values [Hash{Symbol => Object}] Method names mapped to return values

data/lib/taski/version.rb

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

data/lib/taski.rb

@@ -14,6 +14,7 @@ require_relative "taski/execution/tree_progress_display"
 require_relative "taski/execution/simple_progress_display"
 require_relative "taski/execution/plain_progress_display"
 require_relative "taski/args"
+require_relative "taski/env"
 
 module Taski
   class TaskAbortException < StandardError
@@ -138,6 +139,7 @@ module Taski
   end
 
   @args_monitor = Monitor.new
+  @env_monitor = Monitor.new
 
   # Get the current runtime arguments
   # @return [Args, nil] The current args or nil if no task is running
@@ -145,13 +147,50 @@ module Taski
     @args_monitor.synchronize { @args }
   end
 
+  # Get the current execution environment
+  # @return [Env, nil] The current env or nil if no task is running
+  def self.env
+    @env_monitor.synchronize { @env }
+  end
+
+  # Start new execution environment (internal use only)
+  # @api private
+  # @return [Boolean] true if this call created the env, false if env already existed
+  def self.start_env(root_task:)
+    @env_monitor.synchronize do
+      return false if @env
+      @env = Env.new(root_task: root_task)
+      true
+    end
+  end
+
+  # Reset the execution environment (internal use only)
+  # @api private
+  def self.reset_env!
+    @env_monitor.synchronize { @env = nil }
+  end
+
+  # Execute a block with env lifecycle management.
+  # Creates env if it doesn't exist, and resets it only if this call created it.
+  # This prevents race conditions in concurrent execution.
+  #
+  # @param root_task [Class] The root task class
+  # @yield The block to execute with env available
+  # @return [Object] The result of the block
+  def self.with_env(root_task:)
+    created_env = start_env(root_task: root_task)
+    yield
+  ensure
+    reset_env! if created_env
+  end
+
   # Start new runtime arguments (internal use only)
   # @api private
   # @return [Boolean] true if this call created the args, false if args already existed
-  def self.start_args(options:, root_task:)
+  def self.start_args(options:)
     @args_monitor.synchronize do
       return false if @args
-      @args = Args.new(options: options, root_task: root_task)
+      @args = Args.new(options: options)
       true
     end
   end
@@ -167,11 +206,10 @@ module Taski
   # This prevents race conditions in concurrent execution.
   #
   # @param options [Hash] User-defined options
-  # @param root_task [Class] The root task class
   # @yield The block to execute with args available
   # @return [Object] The result of the block
-  def self.with_args(options:, root_task:)
-    created_args = start_args(options: options, root_task: root_task)
+  def self.with_args(options:)
+    created_args = start_args(options: options)
     yield
   ensure
     reset_args! if created_args

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - ahogappa
@@ -72,6 +72,7 @@ files:
 - examples/tree_progress_demo.rb
 - lib/taski.rb
 - lib/taski/args.rb
+- lib/taski/env.rb
 - lib/taski/execution/base_progress_display.rb
 - lib/taski/execution/execution_context.rb
 - lib/taski/execution/executor.rb