roast-ai 0.4.9 → 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_context.rb

@@ -3,52 +3,7 @@
 
 module Roast
   module DSL
-    class ConfigContext
-      def initialize(cogs, config_proc)
-        @cogs = cogs
-        @executor_scoped_configs = {}
-        @cog_scoped_configs = {}
-        @config_proc = config_proc
-      end
-
-      def fetch_merged_config(cog_class, name = nil)
-        # All configs have an entry, even if it's empty.
-        configs = fetch_execution_scope(cog_class)
-        instance_configs = fetch_cog_config(cog_class, name) unless name.nil?
-        configs = configs.merge(instance_configs) if instance_configs
-        configs
-      end
-
-      def prepare!
-        bind_default_cogs
-        instance_eval(&@config_proc)
-      end
-
-      #: () -> void
-      def bind_default_cogs
-        bind_cog(Cogs::Cmd, :cmd)
-      end
-
-      def fetch_cog_config(cog_class, name)
-        @cog_scoped_configs[cog_class][name]
-      end
-
-      def fetch_or_create_cog_config(cog_class, name)
-        @cog_scoped_configs[cog_class][name] = cog_class.config_class.new unless @cog_scoped_configs.key?(name)
-        @cog_scoped_configs[cog_class][name]
-      end
-
-      def fetch_execution_scope(cog_class)
-        @executor_scoped_configs[cog_class]
-      end
-
-      def bind_cog(cog_class, method_name)
-        @cog_scoped_configs[cog_class] = {}
-        @executor_scoped_configs[cog_class] = cog_class.config_class.new
-        instance_eval do
-          define_singleton_method(method_name, &cog_class.on_config)
-        end
-      end
-    end
+    # Context in which the `config` blocks of a workflow definition are evaluated
+    class ConfigContext; end
   end
 end

data/lib/roast/dsl/config_manager.rb

@@ -0,0 +1,143 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    class ConfigManager
+      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
+
+      #: () -> void
+      def prepare!
+        raise ConfigManagerAlreadyPreparedError if preparing? || prepared?
+
+        @preparing = true
+        bind_global
+        bind_registered_cogs
+        @config_procs.each { |cp| @config_context.instance_eval(&cp) }
+        @prepared = true
+      end
+
+      #: () -> bool
+      def preparing?
+        @preparing ||= false
+      end
+
+      #: () -> bool
+      def prepared?
+        @prepared ||= false
+      end
+
+      #: (singleton(Cog), ?Symbol?) -> Cog::Config
+      def config_for(cog_class, name = nil)
+        raise ConfigManagerNotPreparedError unless prepared?
+
+        # All cogs will always have a config; empty by default if the cog was never explicitly configured
+        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
+
+      private
+
+      #: (singleton(Cog)) -> Cog::Config
+      def fetch_general_config(cog_class)
+        @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] ||= {}
+        name_scoped_configs_for_cog[name] ||= cog_class.config_class.new
+      end
+
+      #: () -> void
+      def bind_registered_cogs
+        @cog_registry.cogs.each { |cog_method_name, cog_class| bind_cog(cog_method_name, cog_class) }
+      end
+
+      #: (Symbol, singleton(Cog)) -> void
+      def bind_cog(cog_method_name, cog_class)
+        on_config_method = method(:on_config)
+        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 | 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
+
+        # 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
+          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
+        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
+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_context.rb

@@ -0,0 +1,9 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    # Context in which the `execute` blocks of a workflow definition are evaluated
+    class ExecutionContext; end
+  end
+end