language-operator 0.0.1 → 0.1.31

data/lib/language_operator/dsl/shell.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'open3'
+require 'timeout'
+
+module LanguageOperator
+  module Dsl
+    # Safe shell command execution for MCP tools
+    #
+    # Provides methods for executing shell commands safely with automatic
+    # argument escaping to prevent injection attacks. All methods are class methods.
+    #
+    # @example Basic usage
+    #   result = Shell.run('ls', '-la', '/tmp')
+    #   if result[:success]
+    #     puts result[:output]
+    #   end
+    #
+    # @example Safe user input
+    #   # User input is automatically escaped
+    #   result = Shell.run('grep', user_input, '/etc/hosts')
+    module Shell
+      # Run a shell command with properly escaped arguments
+      #
+      # This is safer than using backticks as it prevents shell injection.
+      # Arguments are automatically escaped using Shellwords.
+      #
+      # @param cmd [String] Command to execute
+      # @param args [Array<String>] Arguments (will be escaped)
+      # @param env [Hash] Environment variables to set
+      # @param chdir [String, nil] Working directory
+      # @param timeout [Integer] Timeout in seconds (default: 30)
+      # @return [Hash] Result with :success, :output, :error, :exitcode, :timeout keys
+      def self.run(cmd, *args, env: {}, chdir: nil, timeout: 30)
+        # Escape all arguments
+        escaped_args = args.map { |arg| Shellwords.escape(arg.to_s) }
+        full_cmd = "#{cmd} #{escaped_args.join(' ')}"
+
+        # Execute with timeout
+        stdout = nil
+        stderr = nil
+        status = nil
+
+        begin
+          Timeout.timeout(timeout) do
+            stdout, stderr, status = Open3.capture3(env, full_cmd, chdir: chdir)
+          end
+        rescue Timeout::Error
+          return {
+            success: false,
+            output: '',
+            error: "Command timed out after #{timeout} seconds",
+            exitcode: -1,
+            timeout: true
+          }
+        rescue StandardError => e
+          return {
+            success: false,
+            output: '',
+            error: e.message,
+            exitcode: -1
+          }
+        end
+
+        {
+          success: status.success?,
+          output: stdout,
+          error: stderr,
+          exitcode: status.exitstatus,
+          timeout: false
+        }
+      end
+
+      # Run a command and return only stdout (like backticks)
+      # Returns nil if the command fails
+      def self.capture(cmd, *, **)
+        result = run(cmd, *, **)
+        result[:success] ? result[:output] : nil
+      end
+
+      # Run a command and return stdout, raising on failure
+      def self.capture!(cmd, *, **)
+        result = run(cmd, *, **)
+        raise "Command failed (exit #{result[:exitcode]}): #{result[:error]}" unless result[:success]
+
+        result[:output]
+      end
+
+      # Check if a command exists in PATH
+      def self.command_exists?(cmd)
+        result = run('which', cmd)
+        result[:success]
+      end
+
+      # Run a command in the background and return immediately
+      # @deprecated This method has been removed for security reasons
+      # @raise [SecurityError] Always raises an error
+      def self.spawn(_cmd, *_args, env: {}, chdir: nil)
+        raise SecurityError, 'Shell.spawn has been removed for security reasons. Background process execution is not allowed in synthesized code.'
+      end
+
+      # Execute raw shell command (REMOVED FOR SECURITY)
+      # This method has been removed as it allowed arbitrary shell execution
+      # with pipes, redirects, etc. which is a security risk in synthesized code.
+      # @deprecated This method has been removed for security reasons
+      # @raise [SecurityError] Always raises an error
+      def self.raw(_command, env: {}, chdir: nil, timeout: 30)
+        raise SecurityError, 'Shell.raw has been removed for security reasons. Use Shell.run with explicit arguments instead.'
+      end
+
+      # Safely build a command string with escaped arguments
+      # Useful when you need to construct a command but not execute it yet
+      def self.build(cmd, *args)
+        escaped_args = args.map { |arg| Shellwords.escape(arg.to_s) }
+        "#{cmd} #{escaped_args.join(' ')}"
+      end
+
+      # Escape a single argument for shell usage
+      def self.escape(arg)
+        Shellwords.escape(arg.to_s)
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/tool_definition.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'parameter_definition'
+require_relative 'http'
+require_relative 'shell'
+require_relative 'helpers'
+
+module LanguageOperator
+  module Dsl
+    # Tool definition for MCP tools
+    #
+    # Defines an MCP tool with parameters, description, and execution logic.
+    # Used within the DSL to create tools that can be registered and served.
+    #
+    # @example Define a simple tool
+    #   tool "greet" do
+    #     description "Greet a user by name"
+    #
+    #     parameter :name do
+    #       type :string
+    #       required true
+    #       description "Name to greet"
+    #     end
+    #
+    #     execute do |params|
+    #       "Hello, #{params['name']}!"
+    #     end
+    #   end
+    class ToolDefinition
+      include LanguageOperator::Dsl::Helpers
+
+      # Provide access to HTTP and Shell helper classes as constants
+      HTTP = LanguageOperator::Dsl::HTTP
+      Shell = LanguageOperator::Dsl::Shell
+
+      attr_reader :name, :parameters, :execute_block
+
+      def initialize(name)
+        @name = name
+        @parameters = {}
+        @execute_block = nil
+        @description = nil
+      end
+
+      def description(val = nil)
+        return @description if val.nil?
+
+        @description = val
+      end
+
+      def parameter(name, &)
+        param = ParameterDefinition.new(name)
+        param.instance_eval(&) if block_given?
+        @parameters[name.to_s] = param
+      end
+
+      def execute(&block)
+        @execute_block = block
+      end
+
+      def call(params)
+        log_debug "Calling tool '#{@name}' with params: #{params.inspect}"
+
+        # Apply default values for missing optional parameters
+        @parameters.each do |name, param_def|
+          default_value = param_def.instance_variable_get(:@default)
+          params[name] = default_value if !params.key?(name) && !default_value.nil?
+
+          # Validate required parameters
+          raise ArgumentError, "Missing required parameter: #{name}" if param_def.required? && !params.key?(name)
+
+          # Validate parameter format if validator is set and value is present
+          if params.key?(name)
+            error = param_def.validate_value(params[name])
+            raise ArgumentError, error if error
+          end
+        end
+
+        # Call the execute block with parameters
+        result = @execute_block.call(params) if @execute_block
+
+        log_debug "Tool '#{@name}' completed: #{truncate_for_log(result)}"
+        result
+      end
+
+      def to_schema
+        {
+          'name' => @name,
+          'description' => @description,
+          'inputSchema' => {
+            'type' => 'object',
+            'properties' => @parameters.transform_values(&:to_schema),
+            'required' => @parameters.select { |_, p| p.required? }.keys
+          }
+        }
+      end
+
+      private
+
+      def log_debug(message)
+        puts "[DEBUG] #{message}" if ENV['DEBUG'] || ENV['MCP_DEBUG']
+      end
+
+      def truncate_for_log(text)
+        return text.inspect if text.nil?
+
+        str = text.to_s
+        str.length > 100 ? "#{str[0..100]}..." : str
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/webhook_authentication.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Defines authentication configuration for webhooks
+    class WebhookAuthentication
+      attr_reader :type, :config
+
+      def initialize
+        @type = nil
+        @config = {}
+      end
+
+      # Verify HMAC signature (GitHub/Stripe style)
+      # @param header [String] Header name containing the signature
+      # @param secret [String] Secret key for HMAC
+      # @param algorithm [Symbol] Hash algorithm (:sha1, :sha256, :sha512)
+      # @param prefix [String, nil] Optional prefix to strip from signature (e.g., "sha256=")
+      def verify_signature(header:, secret:, algorithm: :sha256, prefix: nil)
+        if @current_methods
+          # Inside any_of/all_of - create child auth object
+          auth = WebhookAuthentication.new
+          auth.verify_signature(header: header, secret: secret, algorithm: algorithm, prefix: prefix)
+          @current_methods << auth
+        else
+          @type = :signature
+          @config[:header] = header
+          @config[:secret] = secret
+          @config[:algorithm] = algorithm
+          @config[:prefix] = prefix
+        end
+      end
+
+      # Verify API key from header
+      # @param header [String] Header name containing the API key
+      # @param key [String] Expected API key value
+      def verify_api_key(header:, key:)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_api_key(header: header, key: key)
+          @current_methods << auth
+        else
+          @type = :api_key
+          @config[:header] = header
+          @config[:key] = key
+        end
+      end
+
+      # Verify bearer token
+      # @param token [String] Expected bearer token value
+      def verify_bearer_token(token:)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_bearer_token(token: token)
+          @current_methods << auth
+        else
+          @type = :bearer_token
+          @config[:token] = token
+        end
+      end
+
+      # Verify basic auth credentials
+      # @param username [String] Expected username
+      # @param password [String] Expected password
+      def verify_basic_auth(username:, password:)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_basic_auth(username: username, password: password)
+          @current_methods << auth
+        else
+          @type = :basic_auth
+          @config[:username] = username
+          @config[:password] = password
+        end
+      end
+
+      # Custom authentication callback
+      # @yield [context] Block receives request context hash
+      # @yieldreturn [Boolean] true if authenticated, false otherwise
+      def verify_custom(&block)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_custom(&block)
+          @current_methods << auth
+        else
+          @type = :custom
+          @config[:callback] = block
+        end
+      end
+
+      # Allow multiple authentication methods (any can succeed)
+      def any_of(&block)
+        @type = :any_of
+        @config[:methods] = []
+        @current_methods = @config[:methods]
+        instance_eval(&block) if block
+        @current_methods = nil
+        # Restore type in case it was overwritten by method calls
+        @type = :any_of
+      end
+
+      # Allow multiple authentication methods (all must succeed)
+      def all_of(&block)
+        @type = :all_of
+        @config[:methods] = []
+        @current_methods = @config[:methods]
+        instance_eval(&block) if block
+        @current_methods = nil
+        # Restore type in case it was overwritten by method calls
+        @type = :all_of
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/webhook_definition.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative 'webhook_authentication'
+
+module LanguageOperator
+  module Dsl
+    # Webhook Definition
+    #
+    # Defines webhook endpoints for reactive agents.
+    #
+    # @example Define a webhook with authentication
+    #   webhook "/github/pr-opened" do
+    #     method :post
+    #     authenticate do
+    #       verify_signature header: "X-Hub-Signature-256",
+    #                        secret: ENV['GITHUB_WEBHOOK_SECRET'],
+    #                        algorithm: :sha256,
+    #                        prefix: "sha256="
+    #     end
+    #     on_request do |context|
+    #       # Handle the webhook
+    #     end
+    #   end
+    class WebhookDefinition
+      attr_reader :path, :http_method, :handler, :authentication, :validations
+
+      # Initialize webhook definition
+      #
+      # @param path [String] URL path for the webhook
+      def initialize(path)
+        @path = path
+        @http_method = :post
+        @handler = nil
+        @authentication = nil
+        @validations = []
+      end
+
+      # Set HTTP method
+      #
+      # @param method_name [Symbol] HTTP method (:get, :post, :put, :delete, :patch)
+      # @return [void]
+      def method(method_name)
+        @http_method = method_name
+      end
+
+      # Define authentication for this webhook
+      #
+      # @yield Authentication configuration block
+      # @return [void]
+      def authenticate(&block)
+        @authentication = WebhookAuthentication.new
+        @authentication.instance_eval(&block) if block
+      end
+
+      # Require specific headers
+      #
+      # @param headers [Hash] Required headers and their expected values (nil = just check presence)
+      # @return [void]
+      def require_headers(headers)
+        @validations << { type: :headers, config: headers }
+      end
+
+      # Require specific content type
+      #
+      # @param content_type [String, Array<String>] Allowed content type(s)
+      # @return [void]
+      def require_content_type(*content_types)
+        @validations << { type: :content_type, config: content_types.flatten }
+      end
+
+      # Add custom validation
+      #
+      # @yield [context] Validation block
+      # @yieldreturn [Boolean, String] true if valid, or error message string if invalid
+      # @return [void]
+      def validate(&block)
+        @validations << { type: :custom, config: block }
+      end
+
+      # Define the request handler
+      #
+      # @yield [context] Request handler block
+      # @yieldparam context [Hash] Request context with :path, :method, :headers, :params, :body
+      # @return [void]
+      def on_request(&block)
+        @handler = block
+      end
+
+      # Register this webhook with a web server
+      #
+      # @param web_server [LanguageOperator::Agent::WebServer] Web server instance
+      # @return [void]
+      def register(web_server)
+        return unless @handler
+
+        web_server.register_route(
+          @path,
+          method: @http_method,
+          authentication: @authentication,
+          validations: @validations,
+          &@handler
+        )
+      end
+    end
+  end
+end