language-operator 0.0.1 → 0.1.30

data/lib/language_operator/dsl/execution_context.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Execution context that includes helpers for tool execution
+    #
+    # Provides helper methods during tool execution, allowing tools to access
+    # HTTP, Shell, Config and other utilities directly.
+    #
+    # @example Using in tool execution
+    #   context = LanguageOperator::Dsl::ExecutionContext.new(params)
+    #   context.http_get('https://example.com')
+    #   context.shell('ls -la')
+    class ExecutionContext
+      include LanguageOperator::Dsl::Helpers
+
+      # Provide access to HTTP and Shell helper classes as constants
+      HTTP = LanguageOperator::Dsl::HTTP
+      Shell = LanguageOperator::Dsl::Shell
+
+      # Initialize execution context with parameters
+      #
+      # @param params [Hash] Tool execution parameters
+      def initialize(params)
+        @params = params
+      end
+
+      # Forward missing methods to helpers
+      #
+      # @param method [Symbol] Method name
+      # @param args [Array] Method arguments
+      def method_missing(method, *args)
+        # Allow helper methods to be called directly
+        super
+      end
+
+      # Check if method is available
+      #
+      # @param method [Symbol] Method name
+      # @param include_private [Boolean] Include private methods
+      # @return [Boolean]
+      def respond_to_missing?(method, include_private = false)
+        LanguageOperator::Dsl::Helpers.instance_methods.include?(method) || super
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/helpers.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'shellwords'
+
+module LanguageOperator
+  module Dsl
+    # Common helper methods for MCP tools
+    #
+    # Provides validation, formatting, and utility methods that can be used
+    # within tool execute blocks. All methods are instance methods that get
+    # mixed into the tool execution context.
+    #
+    # @example Using helpers in a tool
+    #   tool "send_email" do
+    #     execute do |params|
+    #       error = validate_email(params["email"])
+    #       return error if error
+    #       # email is valid, proceed...
+    #     end
+    #   end
+    module Helpers
+      # Validate URL format
+      #
+      # @param url [String] URL to validate
+      # @return [String, nil] Error message if invalid, nil if valid
+      def validate_url(url)
+        return 'Error: Invalid URL. Must start with http:// or https://' unless url =~ %r{^https?://}
+
+        nil
+      end
+
+      # Validate phone number in E.164 format
+      #
+      # @param number [String] Phone number to validate
+      # @return [String, nil] Error message if invalid, nil if valid
+      def validate_phone(number)
+        return 'Error: Invalid phone number format. Use E.164 format (e.g., +1234567890)' unless number =~ /^\+\d{10,15}$/
+
+        nil
+      end
+
+      # Validate email address format
+      #
+      # @param email [String] Email address to validate
+      # @return [String, nil] Error message if invalid, nil if valid
+      def validate_email(email)
+        return 'Error: Invalid email format' unless email =~ /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i
+
+        nil
+      end
+
+      # Shell escape for backtick execution (deprecated - use Shell.run instead)
+      # @deprecated This method is deprecated and will be removed for security reasons
+      def shell_escape(str)
+        warn 'DEPRECATION WARNING: shell_escape is deprecated and should not be used'
+        Shellwords.escape(str.to_s)
+      end
+
+      # Run a command and return structured result
+      # @deprecated This method has been removed for security reasons. Use Shell.run instead.
+      # @raise [SecurityError] Always raises an error
+      def run_command(_cmd)
+        raise SecurityError, 'run_command has been removed for security reasons. Use Shell.run instead.'
+      end
+
+      # Check required environment variables
+      def env_required(*vars)
+        missing = vars.reject { |v| ENV.fetch(v, nil) }
+        return "Error: Missing required environment variables: #{missing.join(', ')}" unless missing.empty?
+
+        nil
+      end
+
+      # Get environment variable with fallbacks
+      def env_get(*keys, default: nil)
+        keys.each do |key|
+          value = ENV.fetch(key, nil)
+          return value if value
+        end
+        default
+      end
+
+      # Truncate text to a maximum length
+      def truncate(text, max_length: 2000, suffix: '...')
+        return text if text.length <= max_length
+
+        text[0...max_length] + suffix
+      end
+
+      # Parse comma-separated values
+      def parse_csv(str)
+        return [] if str.nil? || str.empty?
+
+        str.split(',').map(&:strip).reject(&:empty?)
+      end
+
+      # Format error message
+      def error(message)
+        "Error: #{message}"
+      end
+
+      # Format success message
+      def success(message)
+        message
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/http.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'net/http'
+require 'uri'
+require 'json'
+
+module LanguageOperator
+  module Dsl
+    # HTTP client helper for MCP tools
+    #
+    # Provides convenient methods for making HTTP requests from within tools.
+    # Supports GET, POST, PUT, DELETE, HEAD with automatic JSON parsing.
+    #
+    # @example Making a GET request
+    #   result = HTTP.get('https://api.example.com/users')
+    #   if result[:success]
+    #     users = result[:json]
+    #   end
+    class HTTP
+      # Perform a GET request
+      def self.get(url, headers: {}, follow_redirects: true, timeout: 30)
+        uri = parse_uri(url)
+        return { error: "Invalid URL: #{url}" } unless uri
+
+        http = build_http(uri, timeout: timeout)
+        request = Net::HTTP::Get.new(uri)
+        add_headers(request, headers)
+
+        execute_request(http, request, follow_redirects: follow_redirects)
+      end
+
+      # Perform a POST request
+      def self.post(url, body: nil, json: nil, headers: {}, auth: nil, timeout: 30)
+        uri = parse_uri(url)
+        return { error: "Invalid URL: #{url}" } unless uri
+
+        http = build_http(uri, timeout: timeout)
+        request = Net::HTTP::Post.new(uri)
+
+        # Set body
+        if json
+          request.body = json.to_json
+          request['Content-Type'] = 'application/json'
+        elsif body
+          request.body = body
+        end
+
+        add_headers(request, headers)
+        add_auth(request, auth) if auth
+
+        execute_request(http, request)
+      end
+
+      # Perform a PUT request
+      def self.put(url, body: nil, json: nil, headers: {}, auth: nil, timeout: 30)
+        uri = parse_uri(url)
+        return { error: "Invalid URL: #{url}" } unless uri
+
+        http = build_http(uri, timeout: timeout)
+        request = Net::HTTP::Put.new(uri)
+
+        if json
+          request.body = json.to_json
+          request['Content-Type'] = 'application/json'
+        elsif body
+          request.body = body
+        end
+
+        add_headers(request, headers)
+        add_auth(request, auth) if auth
+
+        execute_request(http, request)
+      end
+
+      # Perform a DELETE request
+      def self.delete(url, headers: {}, auth: nil, timeout: 30)
+        uri = parse_uri(url)
+        return { error: "Invalid URL: #{url}" } unless uri
+
+        http = build_http(uri, timeout: timeout)
+        request = Net::HTTP::Delete.new(uri)
+
+        add_headers(request, headers)
+        add_auth(request, auth) if auth
+
+        execute_request(http, request)
+      end
+
+      # Get just the headers from a URL
+      def self.head(url, headers: {}, timeout: 30)
+        uri = parse_uri(url)
+        return { error: "Invalid URL: #{url}" } unless uri
+
+        http = build_http(uri, timeout: timeout)
+        request = Net::HTTP::Head.new(uri)
+        add_headers(request, headers)
+
+        execute_request(http, request)
+      end
+
+      # Wrapper for curl commands (REMOVED FOR SECURITY)
+      # This method has been removed as it executes shell commands via backticks
+      # 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.curl(_url, options: [])
+        raise SecurityError, 'HTTP.curl has been removed for security reasons. Use HTTP.get, HTTP.post, etc. instead.'
+      end
+
+      class << self
+        private
+
+        def parse_uri(url)
+          URI.parse(url)
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def build_http(uri, timeout: 30)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == 'https')
+          http.open_timeout = timeout
+          http.read_timeout = timeout
+          http
+        end
+
+        def add_headers(request, headers)
+          # Add default user agent if not provided
+          request['User-Agent'] ||= 'Langop-SDK/1.0'
+
+          headers.each do |key, value|
+            request[key] = value
+          end
+        end
+
+        def add_auth(request, auth)
+          case auth[:type]
+          when :basic
+            request.basic_auth(auth[:username], auth[:password])
+          when :bearer
+            request['Authorization'] = "Bearer #{auth[:token]}"
+          when :token
+            request['Authorization'] = "Token #{auth[:token]}"
+          end
+        end
+
+        def execute_request(http, request, follow_redirects: false)
+          response = http.request(request)
+
+          # Handle redirects
+          if follow_redirects && response.is_a?(Net::HTTPRedirection)
+            location = response['location']
+            return get(location, headers: request.to_hash, follow_redirects: true)
+          end
+
+          # Parse response
+          result = {
+            status: response.code.to_i,
+            headers: response.to_hash,
+            body: response.body,
+            success: response.is_a?(Net::HTTPSuccess)
+          }
+
+          # Try to parse JSON if content-type indicates JSON
+          if response['content-type']&.include?('application/json')
+            begin
+              result[:json] = JSON.parse(response.body)
+            rescue JSON::ParserError
+              # Body is not valid JSON, leave as string
+            end
+          end
+
+          result
+        rescue StandardError => e
+          {
+            error: e.message,
+            success: false
+          }
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/mcp_server_definition.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'tool_definition'
+
+module LanguageOperator
+  module Dsl
+    # MCP server definition for agents
+    #
+    # Allows agents to expose their own tools via the MCP protocol.
+    # Tools defined here can be called by other agents or MCP clients.
+    #
+    # @example Define tools in an agent
+    #   agent "data-processor" do
+    #     as_mcp_server do
+    #       tool "process_csv" do
+    #         description "Process CSV data"
+    #         parameter :url do
+    #           type :string
+    #           required true
+    #         end
+    #         execute do |params|
+    #           # Processing logic
+    #         end
+    #       end
+    #     end
+    #   end
+    class McpServerDefinition
+      attr_reader :tools, :server_name
+
+      def initialize(agent_name)
+        @agent_name = agent_name
+        @server_name = "#{agent_name}-mcp"
+        @tools = {}
+      end
+
+      # Define a tool that this agent exposes
+      #
+      # @param name [String] Tool name
+      # @yield Tool definition block
+      # @return [ToolDefinition] The tool definition
+      def tool(name, &block)
+        tool_def = ToolDefinition.new(name)
+        tool_def.instance_eval(&block) if block
+        @tools[name] = tool_def
+        tool_def
+      end
+
+      # Set custom server name
+      #
+      # @param name [String] Server name
+      # @return [String] Current server name
+      def name(name = nil)
+        return @server_name if name.nil?
+
+        @server_name = name
+      end
+
+      # Get all tool definitions
+      #
+      # @return [Array<ToolDefinition>] Array of tool definitions
+      def all_tools
+        @tools.values
+      end
+
+      # Check if any tools are defined
+      #
+      # @return [Boolean] True if tools are defined
+      def tools?
+        !@tools.empty?
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/parameter_definition.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Parameter definition for tool parameters
+    #
+    # Defines parameter schema, validation, and metadata for MCP tools.
+    # Supports type checking, required validation, enums, defaults, and custom validators.
+    #
+    # @example Define a required string parameter
+    #   parameter :name do
+    #     type :string
+    #     required true
+    #     description "User's name"
+    #   end
+    #
+    # @example Parameter with enum
+    #   parameter :status do
+    #     type :string
+    #     enum ["active", "inactive", "pending"]
+    #     default "pending"
+    #   end
+    class ParameterDefinition
+      attr_reader :name, :validator
+
+      def initialize(name)
+        @name = name
+        @required = false
+        @validator = nil
+      end
+
+      def type(val = nil)
+        return @type if val.nil?
+
+        @type = val
+      end
+
+      # Setter method for required flag
+      def required(val = true)
+        @required = val
+      end
+
+      # Getter method for required flag (explicit to avoid collision with setter)
+      def required?
+        @required
+      end
+
+      def description(val = nil)
+        return @description if val.nil?
+
+        @description = val
+      end
+
+      def enum(val = nil)
+        return @enum if val.nil?
+
+        @enum = val
+      end
+
+      def default(val = nil)
+        return @default if val.nil?
+
+        @default = val
+      end
+
+      # Custom validation with proc or regex
+      def validate(proc_or_regex)
+        @validator = proc_or_regex
+      end
+
+      # Built-in validators
+      def url_format
+        @validator = %r{^https?://}
+      end
+
+      def email_format
+        @validator = /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i
+      end
+
+      def phone_format
+        @validator = /^\+\d{10,15}$/
+      end
+
+      # Validate a value against this parameter's validator
+      def validate_value(value)
+        return nil unless @validator
+
+        case @validator
+        when Regexp
+          return "Parameter '#{@name}' has invalid format" unless value.to_s =~ @validator
+        when Proc
+          result = @validator.call(value)
+          return result if result.is_a?(String) # Error message
+          return "Parameter '#{@name}' validation failed" unless result
+        end
+
+        nil # No error
+      end
+
+      def to_schema
+        schema = {
+          'type' => map_type(@type),
+          'description' => @description
+        }
+        schema['enum'] = @enum if @enum
+        schema['default'] = @default if @default
+        schema
+      end
+
+      private
+
+      def map_type(ruby_type)
+        case ruby_type
+        when :string then 'string'
+        when :number, :integer then 'number'
+        when :boolean then 'boolean'
+        when :array then 'array'
+        when :object then 'object'
+        else 'string'
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/registry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Registry for storing and retrieving tool definitions
+    #
+    # Manages a collection of tools defined using the DSL.
+    # Tools can be registered, retrieved by name, or accessed as a collection.
+    #
+    # @example Using the registry
+    #   registry = Registry.new
+    #   registry.register(tool_definition)
+    #   all_tools = registry.all
+    class Registry
+      def initialize
+        @tools = {}
+      end
+
+      def register(tool)
+        @tools[tool.name] = tool
+      end
+
+      def get(name)
+        @tools[name]
+      end
+
+      def all
+        @tools.values
+      end
+
+      def clear
+        @tools.clear
+      end
+    end
+  end
+end

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