roast-ai 0.4.10 → 0.5.0

data/lib/roast/dsl/command_runner.rb

@@ -0,0 +1,191 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    # The canonical way to execute shell commands in Roast.
+    #
+    # CommandRunner is the standard command execution interface for DSL cogs
+    # and should be used for all command invocations in this project.
+    #
+    # Features:
+    # - Separate stdout/stderr capture (using Async fibers for concurrency)
+    # - Line-by-line streaming callbacks for custom handling
+    # - Optional timeout support with automatic process cleanup
+    # - Direct command execution (no shell by default for safety)
+    #
+    # Note: Currently executes commands directly without shell features.
+    # Shell support (pipes, redirects, etc.) will be added in a future version.
+    class CommandRunner
+      class CommandRunnerError < StandardError; end
+
+      class NoCommandProvidedError < CommandRunnerError; end
+
+      class TimeoutError < CommandRunnerError; end
+
+      class << self
+        # Execute a command with optional stream handlers
+        #
+        # @param args [Array<String>] Command and arguments as an array
+        # @param timeout [Integer, nil] Timeout in seconds (default: nil, no timeout)
+        # @param stdout_handler [Proc, nil] Called for each stdout line
+        # @param stderr_handler [Proc, nil] Called for each stderr line
+        # @return [Array<String, String, Process::Status>] stdout, stderr, status
+        #
+        # @example Basic usage
+        #   stdout, stderr, status = CommandRunner.execute(["echo", "hello"])
+        #
+        # @example With handlers for streaming output
+        #   CommandRunner.execute(
+        #     ["ls", "-la"],
+        #     stdout_handler: ->(line) { puts "[OUT] #{line}" }
+        #   )
+        #
+        # @example With explicit timeout
+        #   CommandRunner.execute(["sleep", "5"], timeout: 2)  # Will timeout after 2 seconds
+        #: (
+        #|  Array[String],
+        #|  ?working_directory: (Pathname | String)?,
+        #|  ?timeout: (Integer | Float)?,
+        #|  ?stdin_content: String?,
+        #|  ?stdout_handler: (^(String) -> void)?,
+        #|  ?stderr_handler: (^(String) -> void)?,
+        #| ) -> [String, String, Process::Status]
+        def execute(
+          args,
+          working_directory: nil,
+          timeout: nil,
+          stdin_content: nil,
+          stdout_handler: nil,
+          stderr_handler: nil
+        )
+          args.compact!
+          raise NoCommandProvidedError if args.blank?
+
+          stdin, stdout, stderr, wait_thread = Open3 #: as untyped
+            .popen3(
+              { "PWD" => working_directory&.to_s }.compact,
+              *args,
+              { chdir: working_directory }.compact,
+            )
+          stdin.puts stdin_content if stdin_content.present?
+          stdin.close
+          pid = wait_thread.pid
+
+          # If timeout is specified, start a timer in a separate fiber
+          timeout_task = if timeout
+            Async do |task|
+              task.annotate("CommandRunner Timeout Monitor")
+              sleep(timeout)
+              kill_process(pid) if pid
+            end
+          end
+
+          # Read stdout and stderr concurrently
+          stdout_content, stderr_content = Sync do |sync_task|
+            sync_task.annotate("CommandRunner Process Handler")
+            stdout_task = Async do |task|
+              task.annotate("CommandRunner Standard Output Reader")
+              buffer = "" #: String
+              stdout.each_line do |line|
+                buffer += line
+                begin
+                  stdout_handler&.call(line)
+                rescue => e
+                  Roast::Helpers::Logger.debug("stdout_handler raised: #{e.class} - #{e.message}")
+                end
+              end
+              buffer
+            rescue IOError
+              buffer
+            end
+
+            stderr_task = Async do |task|
+              task.annotate("CommandRunner Standard Error Reader")
+              buffer = "" #: String
+              stderr.each_line do |line|
+                buffer += line
+                begin
+                  stderr_handler&.call(line)
+                rescue => e
+                  Roast::Helpers::Logger.debug("stderr_handler raised: #{e.class} - #{e.message}")
+                end
+              end
+              buffer
+            rescue IOError
+              buffer
+            end
+
+            [stdout_task.wait, stderr_task.wait]
+          end
+
+          # Wait for the process to complete
+          status = wait_thread.value
+
+          # Cancel the timeout task if it's still running
+          timeout_task&.stop
+
+          # Check if the process was killed due to timeout
+          if timeout && status.signaled? && (status.termsig == 15 || status.termsig == 9)
+            raise TimeoutError, "Command timed out after #{timeout} seconds"
+          end
+
+          [stdout_content, stderr_content, status]
+        ensure
+          # Clean up resources
+          begin
+            [stdout, stderr].compact.each(&:close)
+          rescue
+            nil
+          end
+          # If we haven't waited for the process yet, kill it
+          if pid && wait_thread&.alive?
+            Async do |task|
+              task.annotate("CommandRunner Process Killer")
+              kill_process(pid)
+            end.wait
+            wait_thread.join(1) # Give it a second to finish
+          end
+        end
+
+        private
+
+        #: (Integer) -> void
+        def kill_process(pid)
+          return unless process_running?(pid)
+
+          # First try TERM signal
+          Process.kill("TERM", pid)
+
+          # Give process a short time to terminate gracefully
+          5.times do
+            sleep(0.02)
+            return unless process_running?(pid)
+          end
+
+          # If still running, use KILL signal
+          Process.kill("KILL", pid) if process_running?(pid)
+
+          # Also try to kill the process group to ensure child processes are killed
+          begin
+            Process.kill("-KILL", pid)
+          rescue
+            nil
+          end
+        rescue Errno::ESRCH
+          # Process already terminated
+        rescue Errno::EPERM
+          Roast::Helpers::Logger.debug("Could not kill process #{pid}: Permission denied")
+        end
+
+        #: (Integer) -> bool
+        def process_running?(pid)
+          Process.getpgid(pid)
+          true
+        rescue Errno::ESRCH
+          false
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/config_manager.rb

@@ -7,13 +7,16 @@ module Roast
       class ConfigManagerError < Roast::Error; end
       class ConfigManagerNotPreparedError < ConfigManagerError; end
       class ConfigManagerAlreadyPreparedError < ConfigManagerError; end
+      class IllegalCogNameError < ConfigManagerError; end
 
       #: (Cog::Registry, Array[^() -> void]) -> void
       def initialize(cog_registry, config_procs)
         @cog_registry = cog_registry
         @config_procs = config_procs
         @config_context = ConfigContext.new #: ConfigContext
+        @global_config = Cog::Config.new #: Cog::Config
         @general_configs = {} #: Hash[singleton(Cog), Cog::Config]
+        @regexp_scoped_configs = {} #: Hash[singleton(Cog), Hash[Regexp, Cog::Config]]
         @name_scoped_configs = {} #: Hash[singleton(Cog), Hash[Symbol, Cog::Config]]
       end
 
@@ -22,6 +25,7 @@ module Roast
         raise ConfigManagerAlreadyPreparedError if preparing? || prepared?
 
         @preparing = true
+        bind_global
         bind_registered_cogs
         @config_procs.each { |cp| @config_context.instance_eval(&cp) }
         @prepared = true
@@ -42,9 +46,16 @@ module Roast
         raise ConfigManagerNotPreparedError unless prepared?
 
         # All cogs will always have a config; empty by default if the cog was never explicitly configured
-        config = fetch_general_config(cog_class)
-        name_scoped_config = fetch_name_scoped_config(cog_class, name) unless name.nil?
-        config = config.merge(name_scoped_config) if name_scoped_config
+        config = cog_class.config_class.new(@global_config.instance_variable_get(:@values).deep_dup)
+        config = config.merge(fetch_general_config(cog_class))
+        @regexp_scoped_configs.fetch(cog_class, {}).select do |pattern, _|
+          pattern.match?(name.to_s) unless name.nil?
+        end.values.each { |cfg| config = config.merge(cfg) }
+        unless name.nil?
+          name_scoped_config = fetch_name_scoped_config(cog_class, name)
+          config = config.merge(name_scoped_config)
+        end
+        config.validate!
         config
       end
 
@@ -55,6 +66,12 @@ module Roast
         @general_configs[cog_class] ||= cog_class.config_class.new
       end
 
+      #: (singleton(Cog), Regexp) -> Cog::Config
+      def fetch_regexp_scoped_config(cog_class, pattern)
+        regexp_scoped_configs_for_cog = @regexp_scoped_configs[cog_class] ||= {}
+        regexp_scoped_configs_for_cog[pattern] ||= cog_class.config_class.new
+      end
+
       #: (singleton(Cog), Symbol) -> Cog::Config
       def fetch_name_scoped_config(cog_class, name)
         name_scoped_configs_for_cog = @name_scoped_configs[cog_class] ||= {}
@@ -69,27 +86,57 @@ module Roast
       #: (Symbol, singleton(Cog)) -> void
       def bind_cog(cog_method_name, cog_class)
         on_config_method = method(:on_config)
-        cog_method = proc do |cog_name = nil, &cog_config_proc|
-          on_config_method.call(cog_class, cog_name, &cog_config_proc)
+        cog_method = proc do |cog_name_or_pattern = nil, &cog_config_proc|
+          on_config_method.call(cog_class, cog_name_or_pattern, cog_config_proc)
         end
         @config_context.instance_eval do
+          raise IllegalCogNameError, cog_method_name if respond_to?(cog_method_name, true)
+
           define_singleton_method(cog_method_name, cog_method)
         end
       end
 
-      #: (singleton(Cog), Symbol) { () -> void } -> void
-      def on_config(cog_class, cog_name, &cog_config_proc)
+      #: (singleton(Cog), (Symbol | Regexp)?, ^() -> void ) -> void
+      def on_config(cog_class, cog_name_or_pattern, cog_config_proc)
         # Called when the cog method is invoked in the workflow's 'config' block.
         # This allows configuration parameters to be set for the cog generally or for a specific named instance
-        config_object = if cog_name.nil?
+
+        # NOTE: cast to untyped is to intentional handling the 'unreachable' else case here.
+        # This method takes user input directly so additional validation with a clearer exception message will be helpful
+        cog_name_or_pattern = cog_name_or_pattern #: untyped
+        config_object = case cog_name_or_pattern
+        when NilClass
           fetch_general_config(cog_class)
+        when Regexp
+          fetch_regexp_scoped_config(cog_class, cog_name_or_pattern)
+        when Symbol
+          fetch_name_scoped_config(cog_class, cog_name_or_pattern)
         else
-          fetch_name_scoped_config(cog_class, cog_name)
+          raise ArgumentError, "Invalid type '#{cog_name_or_pattern.class}' for cog_name_or_pattern"
         end
+
         # NOTE: Sorbet expects the proc passed to instance_exec to be declared as taking an argument
         # but our cog_config_proc does not get an argument
-        config_object.instance_exec(&T.unsafe(cog_config_proc)) if cog_config_proc
-        config_object
+        cog_config_proc = cog_config_proc #: as ^(untyped) -> void
+        config_object.instance_exec(&cog_config_proc) if cog_config_proc
+        nil
+      end
+
+      def bind_global
+        on_global_method = method(:on_global)
+        method_to_bind = proc do |&global_proc|
+          on_global_method.call(global_proc)
+        end
+        @config_context.instance_eval do
+          define_singleton_method(:global, method_to_bind)
+        end
+      end
+
+      #: (^() -> void ) -> void
+      def on_global(global_config_proc)
+        global_config_proc = global_config_proc #: as ^(untyped) -> void
+        @global_config.instance_exec(&global_config_proc) if global_config_proc
+        nil
       end
     end
   end

data/lib/roast/dsl/control_flow.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    # Errors that can be raised to control workflow execution
+    module ControlFlow
+      class Base < StandardError; end
+
+      # Raised in a cog's input block or execute method to terminate the cog and mark it as 'skipped'
+      # without triggering any failure handling
+      class SkipCog < Base; end
+
+      # Raised in a cog's input block or execute method to terminate the cog and mark it as 'failed'
+      # without terminating the workflow. The workflow may abort anyway if the cog is configured to abort the
+      # workflow on failure.
+      class FailCog < Base; end
+
+      # Raised in a cog's input block or execute method to terminate the current loop iteration
+      # and start the next iteration immediately. The current cog will be marked as 'skipped',
+      # and every subsequent cog in the current iteration will not run. Any async cogs currently running in the
+      # current scope will be stopped.
+      #
+      # If this exception is raised outside of a loop (e.g, via the `call` cog, or in the top-level executor),
+      # this exception will just terminate that executor as described above without starting a 'next' iteration.
+      class Next < Base; end
+
+      # Raised in a cog's input block or execute method to terminate the current loop iteration immediately
+      # and skip all subsequent loop iterations. The current cog will be marked as 'skipped',
+      # and every subsequent cog in the current iteration will not run. Any async cogs currently running in the
+      # current scope will be stopped.
+      #
+      # If this exception is raised outside of a loop (e.g, via the `call` cog, or in the top-level executor),
+      # this exception will just terminate that executor as described above without starting a 'next' iteration.
+      #
+      # If this exception is raised inside a `map`, this exception will prevent any subsequent executor invocations
+      # within that map and will stop any async invocations running in parallel.
+      class Break < Base; end
+    end
+  end
+end

data/lib/roast/dsl/execution_manager.rb

@@ -5,23 +5,61 @@ module Roast
   module DSL
     # Context in which the `execute` block of a workflow is evaluated
     class ExecutionManager
+      include SystemCogs::Call::Manager
+      include SystemCogs::Map::Manager
+      include SystemCogs::Repeat::Manager
+
       class ExecutionManagerError < Roast::Error; end
+
       class ExecutionManagerNotPreparedError < ExecutionManagerError; end
+
       class ExecutionManagerAlreadyPreparedError < ExecutionManagerError; end
+
       class ExecutionManagerCurrentlyRunningError < ExecutionManagerError; end
+
       class ExecutionScopeDoesNotExistError < ExecutionManagerError; end
+
       class ExecutionScopeNotSpecifiedError < ExecutionManagerError; end
 
-      #: (Cog::Registry, ConfigManager, Hash[Symbol?, Array[^() -> void]], ?Symbol?) -> void
-      def initialize(cog_registry, config_manager, all_execution_procs, scope = nil)
+      class IllegalCogNameError < ExecutionManagerError; end
+
+      class OutputsAlreadyDefinedError < ExecutionManagerError; end
+
+      #: untyped
+      attr_reader :final_output
+
+      #: (
+      #|  Cog::Registry,
+      #|  ConfigManager,
+      #|  Hash[Symbol?, Array[^() -> void]],
+      #|  WorkflowContext,
+      #|  ?scope: Symbol?,
+      #|  ?scope_value: untyped?,
+      #|  ?scope_index: Integer
+      #| ) -> void
+      def initialize(
+        cog_registry,
+        config_manager,
+        all_execution_procs,
+        workflow_context,
+        scope: nil,
+        scope_value: nil,
+        scope_index: 0
+      )
         @cog_registry = cog_registry
         @config_manager = config_manager
         @all_execution_procs = all_execution_procs
+        @workflow_context = workflow_context
         @scope = scope
+        @scope_value = scope_value
+        @scope_index = scope_index
         @cogs = Cog::Store.new #: Cog::Store
         @cog_stack = Cog::Stack.new #: Cog::Stack
         @execution_context = ExecutionContext.new #: ExecutionContext
-        @cog_input_manager = CogInputManager.new(@cog_registry, @cogs) #: CogInputManager
+        @cog_input_manager = CogInputManager.new(@cog_registry, @cogs, @workflow_context) #: CogInputManager
+        @barrier = Async::Barrier.new #: Async::Barrier
+        @final_output = nil #: untyped
+        @final_output_computed = false #: bool
       end
 
       #: () -> void
@@ -29,6 +67,7 @@ module Roast
         raise ExecutionManagerAlreadyPreparedError if preparing? || prepared?
 
         @preparing = true
+        bind_outputs
         bind_registered_cogs
         my_execution_procs.each { |ep| @execution_context.instance_eval(&ep) }
         @prepared = true
@@ -39,13 +78,33 @@ module Roast
         raise ExecutionManagerCurrentlyRunningError if running?
 
         @running = true
-        @cog_stack.map do |name, cog|
-          cog.run!(
-            @config_manager.config_for(cog.class, name.to_sym),
-            cog_input_manager,
-          )
+        Sync do |sync_task|
+          sync_task.annotate("ExecutionManager #{@scope}")
+          @cog_stack.each do |cog|
+            cog_config = @config_manager.config_for(cog.class, cog.name)
+            cog_task = cog.run!(
+              @barrier,
+              cog_config.deep_dup,
+              cog_input_context,
+              @scope_value.deep_dup,
+              @scope_index,
+            )
+            cog_task.wait unless cog_config.async?
+          end
+          # Wait on the tasks in their completion order, so that an exception in a task will be raised as soon as it occurs
+          # noinspection RubyArgCount
+          @barrier.wait { |task| wait_for_task_with_exception_handling(task) }
+          compute_final_output # eagerly compute the final output (so it, too, can 'break!' subsequent executions in a loop)
+        ensure
+          @barrier.stop
+          compute_final_output
+          @running = false
         end
-        @running = false
+      end
+
+      #: () -> void
+      def stop!
+        @barrier.stop
       end
 
       #: () -> bool
@@ -64,7 +123,7 @@ module Roast
       end
 
       #: () -> CogInputContext
-      def cog_input_manager
+      def cog_input_context
         raise ExecutionManagerNotPreparedError unless prepared?
 
         @cog_input_manager.context
@@ -72,17 +131,32 @@ module Roast
 
       private
 
+      #: (Async::Task) -> void
+      def wait_for_task_with_exception_handling(task)
+        task.wait
+      rescue ControlFlow::Next
+        # TODO: do something with the message passed to next!
+        @barrier.stop
+      rescue ControlFlow::Break => e
+        @barrier.stop
+        compute_final_output # make sure the final output is always computed, even if the iteration is broken
+        raise e
+      rescue StandardError => e
+        @barrier.stop
+        raise e
+      end
+
       #: () -> Array[^() -> void]
       def my_execution_procs
-        raise ExecutionScopeDoesNotExistError unless @all_execution_procs.key?(@scope)
+        raise ExecutionScopeDoesNotExistError, @scope unless @all_execution_procs.key?(@scope)
 
         @all_execution_procs[@scope] || []
       end
 
-      #: (Symbol, Cog) -> void
-      def add_cog_instance(name, cog)
-        @cogs.insert(name, cog)
-        @cog_stack.push([name, cog])
+      #: (Cog) -> void
+      def add_cog_instance(cog)
+        @cogs.insert(cog)
+        @cog_stack.push(cog)
       end
 
       # TODO: add typing for output
@@ -99,38 +173,94 @@ module Roast
       #: (Symbol, singleton(Cog)) -> void
       def bind_cog(cog_method_name, cog_class)
         on_execute_method = method(:on_execute)
-        cog_method = proc do |cog_name = Random.uuid, &cog_input_proc|
-          on_execute_method.call(cog_class, cog_name, &cog_input_proc)
+        cog_method = proc do |*args, **kwargs, &cog_input_proc|
+          on_execute_method.call(cog_class, args, kwargs, cog_input_proc)
         end
         @execution_context.instance_eval do
+          raise IllegalCogNameError, cog_method_name if respond_to?(cog_method_name, true)
+
           define_singleton_method(cog_method_name, cog_method)
         end
       end
 
-      #: (singleton(Cog), Symbol) { (Cog::Input) -> untyped } -> void
-      def on_execute(cog_class, cog_name, &cog_input_proc)
+      #: (singleton(Cog), Array[untyped], Hash[Symbol, untyped], ^(Cog::Input) -> untyped) -> void
+      def on_execute(cog_class, cog_args, cog_kwargs, cog_input_proc)
         # Called when the cog method is invoked in the workflow's 'execute' block.
         # This creates the cog instance and prepares it for execution.
-        cog_instance = if cog_class == Cogs::Execute
-          create_special_execute_cog(cog_name, cog_input_proc)
+        if cog_class <= SystemCog
+          untyped_cog_class = cog_class #: as untyped // to remove warning about splats of unknown length
+          cog_params = untyped_cog_class.params_class.new(*cog_args, **cog_kwargs)
+          cog_instance = if cog_class == SystemCogs::Call
+            create_call_system_cog(cog_params, cog_input_proc)
+          elsif cog_class == SystemCogs::Map
+            create_map_system_cog(cog_params, cog_input_proc)
+          elsif cog_class == SystemCogs::Repeat
+            create_repeat_system_cog(cog_params, cog_input_proc)
+          else
+            raise NotImplementedError, "No system cog manager defined for #{cog_class}"
+          end
         else
-          cog_class.new(cog_name, cog_input_proc)
+          cog_name = Array.wrap(cog_args).shift || Cog.generate_fallback_name
+          cog_instance = cog_class.new(cog_name, cog_input_proc)
         end
-        add_cog_instance(cog_name, cog_instance)
+        add_cog_instance(cog_instance)
       end
 
-      #: (Symbol, ^(Cogs::Execute::Input) -> untyped) -> Cogs::Execute
-      def create_special_execute_cog(cog_name, cog_input_proc)
-        trigger = proc do |input|
-          raise ExecutionScopeNotSpecifiedError unless input.scope.present?
+      def bind_outputs
+        on_outputs_method = method(:on_outputs)
+        on_outputs_bang_method = method(:on_outputs!)
+        method_to_bind = proc { |&outputs_proc| on_outputs_method.call(outputs_proc) }
+        bang_method_to_bind = proc { |&outputs_proc| on_outputs_bang_method.call(outputs_proc) }
+        @execution_context.instance_eval do
+          define_singleton_method(:outputs, method_to_bind)
+          define_singleton_method(:outputs!, bang_method_to_bind)
+        end
+      end
+
+      #: (^(untyped, Integer) -> untyped) -> void
+      def on_outputs(outputs)
+        raise OutputsAlreadyDefinedError if @outputs || @outputs_bang
+
+        @outputs = outputs
+      end
 
-          em = ExecutionManager.new(@cog_registry, @config_manager, @all_execution_procs, input.scope)
-          em.prepare!
-          em.run!
+      #: (^(untyped, Integer) -> untyped) -> void
+      def on_outputs!(outputs)
+        raise OutputsAlreadyDefinedError if @outputs || @outputs_bang
+
+        @outputs_bang = outputs
+      end
+
+      #: () -> untyped
+      def compute_final_output
+        return if @final_output_computed
+
+        @final_output_computed = true
+        outputs_proc = @outputs_bang || @outputs
+
+        @final_output = if outputs_proc
+          @cog_input_manager.context.instance_exec(@scope_value, @scope_index, &outputs_proc)
+        else
+          last_cog_name = @cog_stack.last&.name
+          raise CogInputManager::CogDoesNotExistError, "no cogs defined in scope" unless last_cog_name
 
-          # TODO: collect the outputs of the cogs in the execution manager that just ran and do something with them
+          @cog_input_manager.send(:cog_output, last_cog_name)
         end
-        Cogs::Execute.new(cog_name, cog_input_proc, trigger)
+      rescue ControlFlow::SkipCog, ControlFlow::Next
+        # TODO: do something with the message passed to the control flow statement
+        # Swallow skip! and next! control flow statements in the outputs block
+        # Calling these will just make the final output `nil`.
+        # (As will calling `break!`, but it gets handled elsewhere.)
+        # Calling `fail!` inside `outputs` should actually raise an exception.
+      rescue CogInputManager::CogNotYetRunError, CogInputManager::CogSkippedError, CogInputManager::CogStoppedError => e
+        # Attempting to accessing a cog that was skipped, stopped, or did not run from inside an `outputs` block
+        # is more likely to happen when the user `break!`s from a loop. Allowing this access not to result in an
+        # exception getting raised immediately will reduce boilerplate code needed to check if the loop was broken
+        # and return nil or some fallback value if it was, and the normal outputs value otherwise.
+        #
+        # Using `outputs` to define the scope's outputs will swallow these exceptions.
+        # Using `outputs!` instead will cause the exceptions to be raised.
+        raise e if @outputs_bang.present?
       end
     end
   end

data/lib/roast/dsl/nil_assertions.rb

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+module Kernel
+  #: -> self
+  def not_nil!
+    self
+  end
+end
+
+class NilClass
+  # @override
+  #: -> bot
+  def not_nil!
+    raise UnexpectedNilError
+  end
+end
+
+class UnexpectedNilError < StandardError
+  def initialize(message = "Unexpected nil value encountered.")
+    super(message)
+  end
+end

data/lib/roast/dsl/system_cog/params.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    class SystemCog
+      # Parameters for system cogs set at workflow evaluation time
+      #
+      # Params are used to provide limited evaluation-time parameterization to system cogs,
+      # such as the name of the execute scope to be invoked by a `call`, `map`, a, `repeat` cog.
+      #
+      # System cogs also accept input at execution time, just like regular cogs.
+      class Params
+        # The name identifier for this system cog instance
+        #
+        # Used to reference this cog's output. Auto-generated if not provided.
+        #
+        #: Symbol
+        attr_reader :name
+
+        # Initialize parameters with the cog name
+        #
+        # Subclasses should define their own `initialize` accepting specific parameters.
+        #
+        #: (Symbol?) -> void
+        def initialize(name)
+          @name = name || Cog.generate_fallback_name
+        end
+      end
+    end
+  end
+end