blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # Context represents the workflow execution context passed between nodes.
+    # It carries the request data, response state, variables, and environment.
+    class Context
+      attr_accessor :id, :workflow_name, :workflow_path, :request, :response, :vars, :env
+
+      # @param id [String] Unique execution identifier
+      # @param workflow_name [String] Name of the executing workflow
+      # @param workflow_path [String] Path of the executing workflow
+      # @param request [Request] Incoming request data
+      # @param response [Response] Accumulated response data
+      # @param vars [Hash] Variables shared between nodes
+      # @param env [Hash] Environment variables
+      def initialize(id: "", workflow_name: "", workflow_path: "",
+                     request: nil, response: nil, vars: {}, env: {})
+        @id            = id
+        @workflow_name = workflow_name
+        @workflow_path = workflow_path
+        @request       = request || Request.new
+        @response      = response || Response.new
+        @vars          = vars
+        @env           = env
+      end
+
+      # Build a Context from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [Context]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          id:            hash["id"] || "",
+          workflow_name: hash["workflow_name"] || "",
+          workflow_path: hash["workflow_path"] || "",
+          request:       Request.from_hash(hash["request"]),
+          response:      Response.from_hash(hash["response"]),
+          vars:          hash["vars"] || {},
+          env:           hash["env"] || {}
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        {
+          "id"            => @id,
+          "workflow_name" => @workflow_name,
+          "workflow_path" => @workflow_path,
+          "request"       => @request.to_hash,
+          "response"      => @response.to_hash,
+          "vars"          => @vars,
+          "env"           => @env
+        }
+      end
+
+      # Store a variable in context for downstream nodes.
+      # @param key [String] Variable name
+      # @param value [Object] Variable value
+      def set_var(key, value)
+        @vars[key] = value
+      end
+
+      # Retrieve a variable from context.
+      # @param key [String] Variable name
+      # @return [Object, nil]
+      def get_var(key)
+        @vars[key]
+      end
+
+      # Retrieve a string variable from context.
+      # @param key [String] Variable name
+      # @return [String, nil]
+      def get_var_str(key)
+        val = @vars[key]
+        val.is_a?(String) ? val : nil
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/execution_metrics.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # ExecutionMetrics captures performance metrics for a node execution.
+    class ExecutionMetrics
+      attr_accessor :duration_ms, :cpu_ms, :memory_bytes
+
+      # @param duration_ms [Float, nil] Wall-clock execution time in milliseconds
+      # @param cpu_ms [Float, nil] CPU time in milliseconds
+      # @param memory_bytes [Integer, nil] Peak memory usage in bytes
+      def initialize(duration_ms: nil, cpu_ms: nil, memory_bytes: nil)
+        @duration_ms  = duration_ms
+        @cpu_ms       = cpu_ms
+        @memory_bytes = memory_bytes
+      end
+
+      # Build an ExecutionMetrics from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [ExecutionMetrics]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          duration_ms:  hash["duration_ms"],
+          cpu_ms:       hash["cpu_ms"],
+          memory_bytes: hash["memory_bytes"]
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # Omits nil values to keep the payload compact.
+      # @return [Hash]
+      def to_hash
+        h = {}
+        h["duration_ms"]  = @duration_ms  unless @duration_ms.nil?
+        h["cpu_ms"]       = @cpu_ms       unless @cpu_ms.nil?
+        h["memory_bytes"] = @memory_bytes unless @memory_bytes.nil?
+        h
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/execution_request.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # ExecutionRequest is the request received from the Blok runner.
+    # It wraps the node configuration and the workflow execution context.
+    class ExecutionRequest
+      attr_accessor :node, :context
+
+      # @param node [NodeConfig] Node configuration
+      # @param context [Context] Workflow execution context
+      def initialize(node: nil, context: nil)
+        @node    = node || NodeConfig.new
+        @context = context || Context.new
+      end
+
+      # Build an ExecutionRequest from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [ExecutionRequest]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          node:    NodeConfig.from_hash(hash["node"]),
+          context: Context.from_hash(hash["context"])
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        {
+          "node"    => @node.to_hash,
+          "context" => @context.to_hash
+        }
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/execution_result.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # ExecutionResult is the response returned to the Blok runner after node execution.
+    class ExecutionResult
+      attr_accessor :success, :data, :errors, :logs, :metrics, :vars
+
+      # @param success [Boolean] Whether execution succeeded
+      # @param data [Object] Result data payload
+      # @param errors [Object, nil] Error information
+      # @param logs [Array<String>, nil] Log lines captured during execution
+      # @param metrics [ExecutionMetrics, nil] Performance metrics
+      def initialize(success:, data:, errors: nil, logs: nil, metrics: nil, vars: nil)
+        @success = success
+        @data    = data
+        @errors  = errors
+        @logs    = logs
+        @metrics = metrics
+        @vars    = vars
+      end
+
+      # Create a successful result.
+      # @param data [Object] Result data payload
+      # @return [ExecutionResult]
+      def self.success(data)
+        new(success: true, data: data)
+      end
+
+      # Create a successful result with metrics.
+      # @param data [Object] Result data payload
+      # @param metrics [ExecutionMetrics] Performance metrics
+      # @return [ExecutionResult]
+      def self.success_with_metrics(data, metrics)
+        new(success: true, data: data, metrics: metrics)
+      end
+
+      # Create an error result.
+      # @param message [String] Error message
+      # @return [ExecutionResult]
+      def self.error(message)
+        new(
+          success: false,
+          data:    nil,
+          errors:  { "message" => message }
+        )
+      end
+
+      # Create an error result with details.
+      # @param message [String] Error message
+      # @param details [Object] Additional error details
+      # @return [ExecutionResult]
+      def self.error_with_details(message, details)
+        new(
+          success: false,
+          data:    nil,
+          errors:  { "message" => message, "details" => details }
+        )
+      end
+
+      # Attach log entries to the result.
+      # @param logs [Array<String>] Log lines
+      # @return [self]
+      def with_logs(logs)
+        @logs = logs
+        self
+      end
+
+      # Attach metrics to the result.
+      # @param metrics [ExecutionMetrics] Performance metrics
+      # @return [self]
+      def with_metrics(metrics)
+        @metrics = metrics
+        self
+      end
+
+      # Attach context variables to the result.
+      # @param vars [Hash] Context variables
+      # @return [self]
+      def with_vars(vars)
+        @vars = vars
+        self
+      end
+
+      # Build an ExecutionResult from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [ExecutionResult]
+      def self.from_hash(hash)
+        return error("unknown error") if hash.nil?
+
+        new(
+          success: hash["success"] || false,
+          data:    hash["data"],
+          errors:  hash["errors"],
+          logs:    hash["logs"],
+          metrics: hash["metrics"] ? ExecutionMetrics.from_hash(hash["metrics"]) : nil,
+          vars: hash["vars"]
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # Omits nil optional fields to keep the payload compact.
+      # @return [Hash]
+      def to_hash
+        h = {
+          "success" => @success,
+          "data"    => @data
+        }
+        h["errors"]  = @errors  unless @errors.nil?
+        h["logs"]    = @logs    unless @logs.nil?
+        h["metrics"] = @metrics.to_hash unless @metrics.nil?
+        h["vars"] = @vars unless @vars.nil?
+        h
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/health_status.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # HealthStatus represents the health status of the blok runtime.
+    class HealthStatus
+      attr_accessor :status, :version, :nodes_loaded
+
+      # @param status [String] Health status ("healthy" or "unhealthy")
+      # @param version [String] Runtime version
+      # @param nodes_loaded [Array<String>] Names of registered nodes
+      def initialize(status: "healthy", version: "1.0.0", nodes_loaded: [])
+        @status       = status
+        @version      = version
+        @nodes_loaded = nodes_loaded
+      end
+
+      # Build a HealthStatus from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [HealthStatus]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          status:       hash["status"] || "healthy",
+          version:      hash["version"] || "1.0.0",
+          nodes_loaded: hash["nodes_loaded"] || []
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        {
+          "status"       => @status,
+          "version"      => @version,
+          "nodes_loaded" => @nodes_loaded
+        }
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/node_config.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # NodeConfig represents node-specific configuration from the runner.
+    class NodeConfig
+      attr_accessor :name, :path, :node_type, :config
+
+      # @param name [String] Node name (used for registry lookup)
+      # @param path [String] Node path in the workflow
+      # @param node_type [String] Type of the node
+      # @param config [Hash] Key-value configuration for the node
+      def initialize(name: "", path: "", node_type: "", config: {})
+        @name      = name
+        @path      = path
+        @node_type = node_type
+        @config    = config
+      end
+
+      # Build a NodeConfig from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [NodeConfig]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          name:      hash["name"] || "",
+          path:      hash["path"] || "",
+          node_type: hash["type"] || "",
+          config:    hash["config"] || {}
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        {
+          "name"   => @name,
+          "path"   => @path,
+          "type"   => @node_type,
+          "config" => @config
+        }
+      end
+
+      # Get a string config value with a default.
+      # @param key [String] Config key
+      # @param default [String] Default value
+      # @return [String]
+      def config_str(key, default = "")
+        val = @config[key]
+        val.is_a?(String) ? val : default
+      end
+
+      # Get an integer config value with a default.
+      # @param key [String] Config key
+      # @param default [Integer] Default value
+      # @return [Integer]
+      def config_int(key, default = 0)
+        val = @config[key]
+        val.is_a?(Integer) ? val : default
+      end
+
+      # Get a boolean config value with a default.
+      # @param key [String] Config key
+      # @param default [Boolean] Default value
+      # @return [Boolean]
+      def config_bool(key, default = false)
+        val = @config[key]
+        val == true || val == false ? val : default
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/request.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # Request represents the incoming HTTP request data passed through the workflow context.
+    class Request
+      attr_accessor :body, :headers, :params, :query, :method, :url, :cookies, :base_url
+
+      # @param body [Hash, nil] The request body
+      # @param headers [Hash] HTTP headers
+      # @param params [Hash] URL path parameters
+      # @param query [Hash] URL query parameters
+      # @param method [String] HTTP method
+      # @param url [String] Request URL
+      # @param cookies [Hash] Request cookies
+      # @param base_url [String] Base URL of the request
+      def initialize(body: {}, headers: {}, params: {}, query: {},
+                     method: "", url: "", cookies: {}, base_url: "")
+        @body     = body
+        @headers  = headers
+        @params   = params
+        @query    = query
+        @method   = method
+        @url      = url
+        @cookies  = cookies
+        @base_url = base_url
+      end
+
+      # Build a Request from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [Request]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          body:     hash["body"] || {},
+          headers:  hash["headers"] || {},
+          params:   hash["params"] || {},
+          query:    hash["query"] || {},
+          method:   hash["method"] || "",
+          url:      hash["url"] || "",
+          cookies:  hash["cookies"] || {},
+          base_url: hash["baseUrl"] || ""
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        {
+          "body"    => @body,
+          "headers" => @headers,
+          "params"  => @params,
+          "query"   => @query,
+          "method"  => @method,
+          "url"     => @url,
+          "cookies" => @cookies,
+          "baseUrl" => @base_url
+        }
+      end
+
+      # Get a string value from the body by key.
+      # @param key [String] the body field key
+      # @return [String, nil]
+      def body_str(key)
+        val = @body.is_a?(Hash) ? @body[key] : nil
+        val.is_a?(String) ? val : nil
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/types/response.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Blok
+  module Types
+    # Response represents the workflow response accumulated through node execution.
+    class Response
+      attr_accessor :data, :content_type, :success, :error
+
+      # @param data [Object] Response data
+      # @param content_type [String] Content type of the response
+      # @param success [Boolean] Whether the response is successful
+      # @param error [Object, nil] Error information
+      def initialize(data: nil, content_type: "", success: false, error: nil)
+        @data         = data
+        @content_type = content_type
+        @success      = success
+        @error        = error
+      end
+
+      # Build a Response from a Hash (JSON-parsed).
+      # @param hash [Hash] the parsed JSON hash
+      # @return [Response]
+      def self.from_hash(hash)
+        return new if hash.nil?
+
+        new(
+          data:         hash["data"],
+          content_type: hash["contentType"] || "",
+          success:      hash["success"] || false,
+          error:        hash["error"]
+        )
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        {
+          "data"        => @data,
+          "contentType" => @content_type,
+          "success"     => @success,
+          "error"       => @error
+        }
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/validation/schema_validator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Blok
+  module Validation
+    # SchemaValidator validates data against a JSON Schema (Draft 7 subset).
+    # Supports type checking, required fields, nested properties, enum,
+    # string length constraints, numeric range constraints, and array item validation.
+    class SchemaValidator
+      # Validate data against a schema.
+      # @param data [Object] The data to validate (parsed JSON)
+      # @param schema [Hash] The JSON Schema definition
+      # @return [Array<String>] List of validation error messages (empty if valid)
+      def validate(data, schema)
+        errors = []
+        validate_value(data, schema, "$", errors)
+        errors
+      end
+
+      private
+
+      def validate_value(data, schema, path, errors)
+        return unless schema.is_a?(Hash)
+
+        # Type check
+        if schema.key?("type")
+          expected_type = schema["type"]
+          unless check_type(data, expected_type)
+            errors << "#{path}: expected type \"#{expected_type}\", got #{type_name(data)}"
+            return
+          end
+        end
+
+        # Enum check
+        if schema.key?("enum")
+          enum_values = schema["enum"]
+          if enum_values.is_a?(Array) && !enum_values.include?(data)
+            errors << "#{path}: value not in allowed enum values"
+          end
+        end
+
+        # Object: required fields
+        if schema.key?("required") && data.is_a?(Hash)
+          schema["required"].each do |field|
+            unless data.key?(field)
+              errors << "#{path}: missing required field \"#{field}\""
+            end
+          end
+        end
+
+        # Object: properties
+        if schema.key?("properties") && data.is_a?(Hash)
+          schema["properties"].each do |prop_name, prop_schema|
+            if data.key?(prop_name)
+              validate_value(data[prop_name], prop_schema, "#{path}.#{prop_name}", errors)
+            end
+          end
+        end
+
+        # String constraints
+        if data.is_a?(String)
+          if schema.key?("min_length") || schema.key?("minLength")
+            min = schema["min_length"] || schema["minLength"]
+            if data.length < min
+              errors << "#{path}: string length #{data.length} is less than minimum #{min}"
+            end
+          end
+          if schema.key?("max_length") || schema.key?("maxLength")
+            max = schema["max_length"] || schema["maxLength"]
+            if data.length > max
+              errors << "#{path}: string length #{data.length} exceeds maximum #{max}"
+            end
+          end
+        end
+
+        # Numeric constraints
+        if data.is_a?(Numeric)
+          if schema.key?("minimum")
+            min = schema["minimum"]
+            if data < min
+              errors << "#{path}: value #{data} is less than minimum #{min}"
+            end
+          end
+          if schema.key?("maximum")
+            max = schema["maximum"]
+            if data > max
+              errors << "#{path}: value #{data} exceeds maximum #{max}"
+            end
+          end
+        end
+
+        # Array items
+        if schema.key?("items") && data.is_a?(Array)
+          data.each_with_index do |item, i|
+            validate_value(item, schema["items"], "#{path}[#{i}]", errors)
+          end
+        end
+
+        # Array constraints
+        if data.is_a?(Array)
+          if schema.key?("min_items") || schema.key?("minItems")
+            min = schema["min_items"] || schema["minItems"]
+            if data.length < min
+              errors << "#{path}: array length #{data.length} is less than minimum #{min}"
+            end
+          end
+          if schema.key?("max_items") || schema.key?("maxItems")
+            max = schema["max_items"] || schema["maxItems"]
+            if data.length > max
+              errors << "#{path}: array length #{data.length} exceeds maximum #{max}"
+            end
+          end
+        end
+      end
+
+      def check_type(data, expected)
+        case expected
+        when "string"  then data.is_a?(String)
+        when "number"  then data.is_a?(Numeric)
+        when "integer" then data.is_a?(Integer)
+        when "boolean" then data == true || data == false
+        when "object"  then data.is_a?(Hash)
+        when "array"   then data.is_a?(Array)
+        when "null"    then data.nil?
+        else true
+        end
+      end
+
+      def type_name(data)
+        case data
+        when nil    then "null"
+        when true, false then "boolean"
+        when Integer then "integer"
+        when Numeric then "number"
+        when String  then "string"
+        when Array   then "array"
+        when Hash    then "object"
+        else data.class.name
+        end
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/lib/blok/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Blok
+  VERSION = "1.0.0"
+end