blokctl 1.3.0 → 1.4.1

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Blok
+  module Errors
+    # Bounded slice of inputs + recent vars for the
+    # +BlokError#context_snapshot+ field, per master plan §17.6.
+    #
+    # Default budget: 4 KB serialized + last-16 vars keys, with progressive
+    # trimming when oversize. +inputs+ is preserved as-is — it's the most
+    # LLM-actionable context. Mirrors Python's +build_context_snapshot+, Go's
+    # +BuildContextSnapshot+, Rust's +build_context_snapshot+, Java's
+    # +BuildContextSnapshot.of+, and C#'s +BuildContextSnapshot.Of+.
+    module BuildContextSnapshot
+      module_function
+
+      # Snapshot of +inputs+ + last-16 vars keys, capped at 4 KB.
+      # @param inputs [Hash, nil]
+      # @param vars [Hash, nil]
+      # @return [Hash]
+      def of(inputs:, vars:)
+        with_opts(inputs: inputs, vars: vars,
+                  max_bytes: BlokError::CONTEXT_SNAPSHOT_MAX_BYTES, max_vars_keys: 16)
+      end
+
+      # Customizable variant of {.of}. +max_vars_keys+ = 0 drops vars
+      # entirely. +max_bytes+ <= 0 disables byte-budget trimming.
+      # @param inputs [Hash, nil]
+      # @param vars [Hash, nil]
+      # @param max_bytes [Integer]
+      # @param max_vars_keys [Integer]
+      # @return [Hash]
+      def with_opts(inputs:, vars:, max_bytes:, max_vars_keys:)
+        safe_inputs = json_safe(inputs || {})
+
+        # Sort vars keys for a deterministic "last N" slice. Ruby Hash since
+        # 1.9 is insertion-ordered, but tests need cross-runtime determinism;
+        # mirroring Java's TreeMap, Rust's BTreeMap, and C#'s SortedDictionary.
+        sorted_keys = (vars || {}).keys.map(&:to_s).sort
+        if max_vars_keys >= 0 && sorted_keys.length > max_vars_keys
+          sorted_keys = sorted_keys.last(max_vars_keys)
+        end
+
+        recent = build_recent(vars, sorted_keys)
+        snapshot = { "inputs" => safe_inputs, "vars" => recent }
+
+        return snapshot if max_bytes <= 0
+        return snapshot if encoded_bytes(snapshot) <= max_bytes
+
+        # Trim from the front (oldest keys) until the snapshot fits.
+        while !sorted_keys.empty?
+          sorted_keys = sorted_keys[1..]
+          snapshot["vars"] = build_recent(vars, sorted_keys)
+          return snapshot if encoded_bytes(snapshot) <= max_bytes
+        end
+
+        { "inputs" => safe_inputs, "vars" => {}, "_truncated" => true }
+      end
+
+      # ===== Internal helpers ================================================
+
+      def encoded_bytes(value)
+        JSON.generate(value).bytesize
+      rescue JSON::JSONError
+        Float::INFINITY
+      end
+
+      def build_recent(vars, keys)
+        return {} if vars.nil?
+        keys.each_with_object({}) do |k, out|
+          # Hash#fetch supports both string and symbol keys.
+          val = vars[k] || vars[k.to_sym]
+          out[k] = json_safe(val)
+        end
+      end
+
+      def json_safe(value)
+        case value
+        when nil, true, false, Numeric, String
+          value
+        when Symbol
+          value.to_s
+        when Hash
+          value.each_with_object({}) { |(k, v), out| out[k.to_s] = json_safe(v) }
+        when Array
+          value.map { |v| json_safe(v) }
+        else
+          # Try a JSON round-trip; fall back to to_s for un-serializable values.
+          begin
+            JSON.parse(JSON.generate(value))
+          rescue JSON::JSONError
+            value.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Blok
+  module Errors
+    # ErrorCategory classifies the type of error that occurred during node execution.
+    module ErrorCategory
+      VALIDATION    = "VALIDATION"
+      EXECUTION     = "EXECUTION"
+      CONFIGURATION = "CONFIGURATION"
+      NETWORK       = "NETWORK"
+      NOT_FOUND     = "NOT_FOUND"
+
+      ALL = [VALIDATION, EXECUTION, CONFIGURATION, NETWORK, NOT_FOUND].freeze
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Blok
+  module Errors
+    # NodeError represents a structured error from node execution.
+    # It carries a human-readable message, an HTTP-style code, an error category,
+    # and optional structured details.
+    class NodeError < StandardError
+      attr_reader :node_message, :code, :category, :details
+
+      # @param message [String] Human-readable error message
+      # @param code [Integer] HTTP-style error code
+      # @param category [String] One of ErrorCategory constants
+      # @param details [Hash, nil] Optional structured error details
+      def initialize(message, code:, category:, details: nil)
+        @node_message = message
+        @code         = code
+        @category     = category
+        @details      = details
+        super(message)
+      end
+
+      # Create a validation error (400).
+      # @param message [String] Error message
+      # @return [NodeError]
+      def self.validation(message)
+        new(message, code: 400, category: ErrorCategory::VALIDATION)
+      end
+
+      # Create an execution error (500).
+      # @param message [String] Error message
+      # @return [NodeError]
+      def self.execution(message)
+        new(message, code: 500, category: ErrorCategory::EXECUTION)
+      end
+
+      # Create a configuration error (500).
+      # @param message [String] Error message
+      # @return [NodeError]
+      def self.configuration(message)
+        new(message, code: 500, category: ErrorCategory::CONFIGURATION)
+      end
+
+      # Create a network error (502).
+      # @param message [String] Error message
+      # @return [NodeError]
+      def self.network(message)
+        new(message, code: 502, category: ErrorCategory::NETWORK)
+      end
+
+      # Create a not-found error (404).
+      # @param message [String] Error message
+      # @return [NodeError]
+      def self.not_found(message)
+        new(message, code: 404, category: ErrorCategory::NOT_FOUND)
+      end
+
+      # Attach details to the error (returns a new instance).
+      # @param details [Hash] Additional details
+      # @return [NodeError]
+      def with_details(details)
+        self.class.new(@node_message, code: @code, category: @category, details: details)
+      end
+
+      # Convert to a Hash for JSON serialization.
+      # @return [Hash]
+      def to_hash
+        h = {
+          "message"  => @node_message,
+          "code"     => @code,
+          "category" => @category
+        }
+        h["details"] = @details unless @details.nil?
+        h
+      end
+
+      # Display format: [CATEGORY] message
+      # @return [String]
+      def to_s
+        "[#{@category}] #{@node_message}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Blok
+  module Logging
+    # LogEntry represents a single structured log entry captured during node execution.
+    class LogEntry
+      attr_reader :level, :message, :timestamp, :fields
+
+      # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+      # @param message [String] Log message
+      # @param timestamp [String] ISO 8601 timestamp
+      # @param fields [Hash, nil] Optional structured fields
+      def initialize(level:, message:, timestamp: nil, fields: nil)
+        @level     = level
+        @message   = message
+        @timestamp = timestamp || Time.now.utc.iso8601
+        @fields    = fields
+      end
+
+      # Format the log entry as a human-readable string.
+      # @return [String]
+      def to_s
+        label = LogLevel.label(@level)
+        if @fields
+          "[#{label}] #{@timestamp} #{@message} #{JSON.generate(@fields)}"
+        else
+          "[#{label}] #{@timestamp} #{@message}"
+        end
+      end
+
+      # Serialize to a Hash suitable for JSON output.
+      # @return [Hash]
+      def to_hash
+        h = {
+          "level"     => LogLevel.label(@level),
+          "message"   => @message,
+          "timestamp" => @timestamp
+        }
+        h["fields"] = @fields unless @fields.nil?
+        h
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Blok
+  module Logging
+    # LogLevel defines the severity levels for structured logging.
+    # Levels are ordered: debug < info < warn < error.
+    module LogLevel
+      DEBUG = :debug
+      INFO  = :info
+      WARN  = :warn
+      ERROR = :error
+
+      ALL = [DEBUG, INFO, WARN, ERROR].freeze
+
+      PRIORITY = {
+        debug: 0,
+        info:  1,
+        warn:  2,
+        error: 3
+      }.freeze
+
+      # Return the integer priority for a given level symbol.
+      # @param level [Symbol] Log level
+      # @return [Integer]
+      def self.priority(level)
+        PRIORITY.fetch(level, 1)
+      end
+
+      # Return the uppercase string label for a given level symbol.
+      # @param level [Symbol] Log level
+      # @return [String]
+      def self.label(level)
+        level.to_s.upcase
+      end
+
+      # Parse a string into a log level symbol.
+      # @param str [String] Level string (e.g. "DEBUG", "info")
+      # @return [Symbol]
+      def self.parse(str)
+        case str.to_s.downcase
+        when "debug" then DEBUG
+        when "warn"  then WARN
+        when "error" then ERROR
+        else INFO
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Blok
+  module Logging
+    # Logger captures structured log entries during node execution.
+    # Thread-safe via Mutex. Entries can be retrieved for inclusion
+    # in ExecutionResult.logs.
+    class Logger
+      # @param min_level [Symbol] Minimum log level to capture (default: :info)
+      def initialize(min_level = LogLevel::INFO)
+        @min_level = min_level
+        @entries   = []
+        @mutex     = Mutex.new
+      end
+
+      # Log a debug message.
+      # @param message [String] Log message
+      # @param fields [Hash, nil] Optional structured fields
+      def debug(message, fields: nil)
+        log(LogLevel::DEBUG, message, fields)
+      end
+
+      # Log an info message.
+      # @param message [String] Log message
+      # @param fields [Hash, nil] Optional structured fields
+      def info(message, fields: nil)
+        log(LogLevel::INFO, message, fields)
+      end
+
+      # Log a warning message.
+      # @param message [String] Log message
+      # @param fields [Hash, nil] Optional structured fields
+      def warn(message, fields: nil)
+        log(LogLevel::WARN, message, fields)
+      end
+
+      # Log an error message.
+      # @param message [String] Log message
+      # @param fields [Hash, nil] Optional structured fields
+      def error(message, fields: nil)
+        log(LogLevel::ERROR, message, fields)
+      end
+
+      # Return all captured log entries.
+      # @return [Array<LogEntry>]
+      def entries
+        @mutex.synchronize { @entries.dup }
+      end
+
+      # Return log entries as formatted strings for ExecutionResult.logs.
+      # @return [Array<String>]
+      def lines
+        @mutex.synchronize { @entries.map(&:to_s) }
+      end
+
+      # Clear all captured entries.
+      def clear
+        @mutex.synchronize { @entries.clear }
+      end
+
+      private
+
+      def log(level, message, fields)
+        return if LogLevel.priority(level) < LogLevel.priority(@min_level)
+
+        entry = LogEntry.new(level: level, message: message, fields: fields)
+        @mutex.synchronize { @entries << entry }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Blok
+  module Middleware
+    # LoggingMiddleware logs node execution with timing information.
+    # It captures start/complete/failed events using the provided Logger.
+    class LoggingMiddleware < Middleware
+      # @param logger [Blok::Logging::Logger] Logger instance
+      def initialize(logger)
+        super()
+        @logger = logger
+      end
+
+      # Wrap the handler with logging behavior.
+      # @param handler [#call] Inner handler callable
+      # @return [#call] Wrapped callable with logging
+      def wrap(handler)
+        logger = @logger
+
+        ->(ctx, config) {
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          logger.info("node execution started", fields: { "workflow" => ctx.workflow_name })
+
+          begin
+            result = handler.call(ctx, config)
+            duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+            logger.info("node execution completed", fields: {
+              "workflow"    => ctx.workflow_name,
+              "duration_ms" => duration_ms.round(2)
+            })
+            result
+          rescue StandardError => e
+            duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+            logger.error("node execution failed", fields: {
+              "workflow"    => ctx.workflow_name,
+              "duration_ms" => duration_ms.round(2),
+              "error"       => e.message
+            })
+            raise
+          end
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Blok
+  module Middleware
+    # Middleware is the base class for execution pipeline middleware.
+    # Each middleware wraps a callable (lambda/proc) and returns
+    # a new callable with additional behavior.
+    #
+    # Subclasses must implement +wrap+ which receives the inner handler
+    # (a callable responding to +call(ctx, config)+) and returns a new
+    # callable with the same signature.
+    #
+    # @example
+    #   class MyMiddleware < Blok::Middleware::Middleware
+    #     def wrap(handler)
+    #       ->(ctx, config) {
+    #         # pre-processing
+    #         result = handler.call(ctx, config)
+    #         # post-processing
+    #         result
+    #       }
+    #     end
+    #   end
+    #
+    class Middleware
+      # Wrap the inner handler and return a new callable.
+      #
+      # @param handler [#call] A callable that accepts (ctx, config)
+      # @return [#call] A wrapped callable
+      # @raise [NotImplementedError] if not overridden
+      def wrap(handler)
+        raise NotImplementedError, "#{self.class}#wrap must be implemented"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Blok
+  module Middleware
+    # RecoveryMiddleware rescues unhandled exceptions and converts them
+    # into structured error results, preventing the runtime from crashing.
+    class RecoveryMiddleware < Middleware
+      # Wrap the handler with exception recovery.
+      # @param handler [#call] Inner handler callable
+      # @return [#call] Wrapped callable with recovery
+      def wrap(handler)
+        ->(ctx, config) {
+          begin
+            handler.call(ctx, config)
+          rescue Errors::BlokError
+            # Master plan §17 BlokError passes through verbatim — the
+            # registry catches it directly and stashes the typed instance
+            # on `ExecutionResult.errors` for the gRPC servicer.
+            raise
+          rescue Errors::NodeError
+            # Legacy structured exceptions pass through as-is too.
+            raise
+          rescue StandardError => e
+            # Convert unexpected errors into a structured error response
+            raise Errors::NodeError.execution("unexpected error: #{e.message}")
+          end
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "node_handler"
+
+module Blok
+  module Node
+    # Discover + register user-authored node handlers from a directory.
+    #
+    # Each user node lives in `<nodes_dir>/<name>/node.rb` and defines a class
+    # `class <Pascal>Node < Blok::Node::NodeHandler` (or `< TypedNode`). We
+    # `require` each file, then register only the NodeHandler subclasses defined
+    # during THIS call — the same before/after snapshot the Python SDK uses
+    # (`_DECORATED_NODES[before:]`). Purely additive, so the SDK's built-in nodes
+    # (registered earlier in serve.rb) are untouched.
+    #
+    # Node name resolution (explicit, deterministic — no ObjectSpace scan):
+    #   1. `klass.node_name` when the class declares one (TypedNode authors), else
+    #   2. the class name with a trailing "Node" dropped, demodulized + kebab-cased:
+    #      `GreetUser` -> "greet-user", `FooNode` -> "foo".
+    #
+    # Returns the number of newly registered nodes. A file that fails to require
+    # is logged to stderr and skipped so one bad node can't sink the runtime.
+    #
+    # @param registry [NodeRegistry] the registry to populate
+    # @param nodes_dir [String, nil] BLOK_NODES_DIR (project's runtimes/ruby/nodes)
+    # @return [Integer] count of newly registered user nodes
+    def self.load_user_nodes(registry, nodes_dir)
+      return 0 if nodes_dir.nil? || nodes_dir.empty? || !File.directory?(nodes_dir)
+
+      before = NodeHandler::DESCENDANTS.length
+
+      Dir.children(nodes_dir).sort.each do |entry|
+        node_file = File.join(nodes_dir, entry, "node.rb")
+        next unless File.file?(node_file)
+
+        begin
+          require File.expand_path(node_file)
+        rescue StandardError, LoadError, SyntaxError => e
+          warn "[blok][discovery] failed to load #{node_file}: #{e.class}: #{e.message}"
+        end
+      end
+
+      new_classes = NodeHandler::DESCENDANTS[before..] || []
+      new_classes.each do |klass|
+        registry.register(node_name_for(klass), klass.new)
+      end
+      new_classes.length
+    end
+
+    # Resolve the registration name for a discovered handler class.
+    def self.node_name_for(klass)
+      declared = klass.respond_to?(:node_name) ? klass.node_name : nil
+      return declared.to_s unless declared.nil? || declared.to_s.empty?
+
+      base = klass.name.to_s.split("::").last.to_s.sub(/Node\z/, "")
+      base.gsub(/([a-z\d])([A-Z])/, '\1-\2').downcase
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Blok
+  module Node
+    # NodeHandler is the base class that all Blok nodes must inherit from.
+    #
+    # Subclasses must implement the +execute+ method which receives the
+    # workflow context and node-specific configuration, and returns a
+    # data hash (or any JSON-serializable value).
+    #
+    # @example
+    #   class GreetNode < Blok::Node::NodeHandler
+    #     def execute(ctx, config)
+    #       name = ctx.request.body_str("name") || "World"
+    #       prefix = config["prefix"] || "Hello"
+    #       { "message" => "#{prefix}, #{name}!" }
+    #     end
+    #   end
+    #
+    class NodeHandler
+      # Subclasses defined anywhere (SDK built-ins + user nodes) are collected
+      # here in definition order. `Blok::Node.load_user_nodes` snapshots this
+      # list before/after requiring each user file and registers only the new
+      # subclasses — an explicit, traceable discovery rule (no ObjectSpace scan).
+      DESCENDANTS = []
+
+      def self.inherited(subclass)
+        super
+        DESCENDANTS << subclass
+      end
+
+      # Execute the node logic.
+      #
+      # @param ctx [Blok::Types::Context] The workflow execution context
+      # @param config [Hash] Node-specific configuration
+      # @return [Object] JSON-serializable result data
+      # @raise [NotImplementedError] if not overridden by a subclass
+      def execute(ctx, config)
+        raise NotImplementedError, "#{self.class}#execute must be implemented"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Blok
+  module Node
+    # NodeRegistry manages registered node handlers and dispatches
+    # execution requests. It holds a map of node names to handler instances,
+    # applies middleware, and measures execution timing.
+    class NodeRegistry
+      # @param version [String] Runtime version string
+      def initialize(version = Blok::VERSION)
+        @nodes      = {}
+        @middlewares = []
+        @version    = version
+      end
+
+      # Register a node handler under the given name.
+      # @param name [String] Node name (used for dispatch)
+      # @param handler [NodeHandler] Handler instance
+      def register(name, handler)
+        @nodes[name] = handler
+      end
+
+      # Look up a node handler by name.
+      # @param name [String] Node name
+      # @return [NodeHandler, nil]
+      def get(name)
+        @nodes[name]
+      end
+
+      # Add a middleware to the execution pipeline.
+      # @param middleware [Middleware::Middleware] Middleware instance
+      def use(middleware)
+        @middlewares << middleware
+      end
+
+      # Return the names of all registered nodes.
+      # @return [Array<String>]
+      def node_names
+        @nodes.keys.sort
+      end
+
+      # Execute a node by dispatching through the registry.
+      # Returns an ExecutionResult with timing metrics.
+      #
+      # @param execution_request [Types::ExecutionRequest] The execution request
+      # @return [Types::ExecutionResult]
+      def execute(execution_request)
+        node_name = execution_request.node.name
+        handler   = get(node_name)
+
+        unless handler
+          return Types::ExecutionResult.error("node '#{node_name}' not found in registry")
+        end
+
+        # Build a callable that invokes the handler
+        callable = ->(ctx, config) { handler.execute(ctx, config) }
+
+        # Apply middleware chain (each middleware wraps the callable)
+        @middlewares.each do |mw|
+          callable = mw.wrap(callable)
+        end
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          data = callable.call(execution_request.context, execution_request.node.config)
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+
+          metrics = Types::ExecutionMetrics.new(duration_ms: duration_ms)
+          result = Types::ExecutionResult.success_with_metrics(data, metrics)
+
+          # Include context vars so the runner can propagate them downstream
+          ctx_vars = execution_request.context.vars
+          result.with_vars(ctx_vars) if ctx_vars && !ctx_vars.empty?
+
+          result
+        rescue Errors::BlokError => e
+          # Structured BlokError path (master plan §17): pass the instance
+          # through verbatim so the gRPC servicer can serialize every field
+          # (category, severity, remediation, retryable hints, cause chain,
+          # context snapshot, etc.) into the proto NodeError.
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+          result = Types::ExecutionResult.new(success: false, data: nil, errors: e)
+          result.with_metrics(Types::ExecutionMetrics.new(duration_ms: duration_ms))
+        rescue Errors::NodeError => e
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+          result = Types::ExecutionResult.error_with_details(e.message, e.to_hash)
+          result.with_metrics(Types::ExecutionMetrics.new(duration_ms: duration_ms))
+        rescue StandardError => e
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+          result = Types::ExecutionResult.error(e.message)
+          result.with_metrics(Types::ExecutionMetrics.new(duration_ms: duration_ms))
+        end
+      end
+
+      # Return the health status of the runtime.
+      # @return [Types::HealthStatus]
+      def health
+        Types::HealthStatus.new(
+          status:       "healthy",
+          version:      @version,
+          nodes_loaded: node_names
+        )
+      end
+    end
+  end
+end