blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/ruby/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

package/dist/scaffold-repo/sdks/ruby/README.md

@@ -0,0 +1,210 @@
+# Blok Ruby SDK
+
+Production-ready Ruby SDK for building [Blok](https://github.com/blok-dev/sdks) workflow nodes. Each node runs inside a Docker container exposing a simple HTTP protocol:
+
+- **POST /execute** -- Receives an `ExecutionRequest` (JSON), returns an `ExecutionResult` (JSON), always HTTP 200.
+- **GET /health** -- Returns a `HealthStatus` (JSON) with loaded node names.
+
+## Requirements
+
+- Ruby >= 3.1
+- Bundler >= 2.0
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "blok-ruby"
+```
+
+Or install directly:
+
+```sh
+gem install blok-ruby
+```
+
+## Quick Start
+
+### 1. Create a node
+
+```ruby
+# my_node.rb
+require "blok"
+
+class GreetNode < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    name   = ctx.request.body_str("name") || "World"
+    prefix = config["prefix"] || "Hello"
+
+    message = "#{prefix}, #{name}!"
+    ctx.set_var("greeting", message)
+
+    { "message" => message, "language" => "ruby" }
+  end
+end
+```
+
+### 2. Register and run
+
+```ruby
+# config.ru
+require "blok"
+require_relative "my_node"
+
+registry = Blok::Server::RuntimeApp.registry
+registry.register("greet", GreetNode.new)
+
+run Blok::Server::RuntimeApp
+```
+
+```sh
+bundle exec rackup --host 0.0.0.0 --port 8080
+```
+
+### 3. Test it
+
+```sh
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "node": { "name": "greet", "config": { "prefix": "Hi" } },
+    "context": {
+      "id": "exec-1",
+      "request": { "body": { "name": "Blok" } }
+    }
+  }'
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": { "message": "Hi, Blok!", "language": "ruby" },
+  "metrics": { "duration_ms": 0.42 }
+}
+```
+
+## Configuration
+
+Use environment variables to configure the runtime:
+
+| Variable      | Default   | Description                     |
+|---------------|-----------|---------------------------------|
+| `PORT`        | `8080`    | HTTP server port                |
+| `HOST`        | `0.0.0.0` | Bind address                   |
+| `VERSION`     | `1.0.0`   | Runtime version                 |
+| `LOG_LEVEL`   | `INFO`    | Minimum log level (DEBUG/INFO/WARN/ERROR) |
+| `ENABLE_CORS` | `false`   | Enable CORS headers             |
+
+```ruby
+config = Blok::Config::ServerConfig.from_env
+```
+
+## Middleware
+
+Add cross-cutting concerns to the execution pipeline:
+
+```ruby
+logger = Blok::Logging::Logger.new(:debug)
+
+registry = Blok::Node::NodeRegistry.new
+registry.use(Blok::Middleware::LoggingMiddleware.new(logger))
+registry.use(Blok::Middleware::RecoveryMiddleware.new)
+registry.register("my-node", MyNode.new)
+```
+
+### Custom Middleware
+
+```ruby
+class TimingMiddleware < Blok::Middleware::Middleware
+  def wrap(handler)
+    ->(ctx, config) {
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = handler.call(ctx, config)
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      puts "Node executed in #{(elapsed * 1000).round(2)}ms"
+      result
+    }
+  end
+end
+```
+
+## Schema Validation
+
+Validate data against JSON Schema (subset):
+
+```ruby
+validator = Blok::Validation::SchemaValidator.new
+
+schema = {
+  "type" => "object",
+  "required" => ["name", "email"],
+  "properties" => {
+    "name"  => { "type" => "string", "minLength" => 1 },
+    "email" => { "type" => "string" }
+  }
+}
+
+errors = validator.validate({ "name" => "John" }, schema)
+# => ["$: missing required field \"email\""]
+```
+
+## Error Handling
+
+Use structured errors with categories:
+
+```ruby
+raise Blok::Errors::NodeError.validation("name is required")
+raise Blok::Errors::NodeError.configuration("missing API key")
+raise Blok::Errors::NodeError.network("connection timed out")
+raise Blok::Errors::NodeError.not_found("user not found")
+raise Blok::Errors::NodeError.execution("unexpected failure")
+```
+
+## Testing
+
+### MockContext Builder
+
+```ruby
+require "minitest/autorun"
+require "blok"
+
+class GreetNodeTest < Minitest::Test
+  def test_greet_default
+    ctx = Blok::Testing::MockContext.new
+      .with_body({ "name" => "World" })
+      .build
+
+    node   = GreetNode.new
+    result = node.execute(ctx, {})
+
+    assert_equal "Hello, World!", result["message"]
+  end
+end
+```
+
+### TestRunner
+
+```ruby
+runner = Blok::Testing::TestRunner.new
+runner.register("greet", GreetNode.new)
+
+ctx = Blok::Testing::MockContext.new.with_body({ "name" => "Test" }).build
+result = runner.execute("greet", ctx, { "prefix" => "Hi" })
+
+assert result.success
+assert_equal "Hi, Test!", result.data["message"]
+```
+
+## Docker
+
+```sh
+docker build -t my-node .
+docker run -p 8080:8080 my-node
+```
+
+## License
+
+MIT

package/dist/scaffold-repo/sdks/ruby/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

package/dist/scaffold-repo/sdks/ruby/blok.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/blok/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "blok-ruby"
+  spec.version       = Blok::VERSION
+  spec.authors       = ["Blok Team"]
+  spec.email         = ["team@blok.dev"]
+
+  spec.summary       = "Ruby SDK for the Blok blok framework"
+  spec.description   = "Production-ready Ruby SDK for building Blok workflow nodes. " \
+                        "Provides a base node handler, HTTP runtime server, middleware pipeline, " \
+                        "structured logging, schema validation, and testing utilities."
+  spec.homepage      = "https://github.com/blok-dev/sdks"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/blok-dev/sdks/tree/main/ruby"
+  spec.metadata["changelog_uri"]   = "https://github.com/blok-dev/sdks/blob/main/ruby/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{lib,examples}/**/*", "Gemfile", "Rakefile", "config.ru", "README.md", "LICENSE.txt"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "sinatra",  "~> 4.0"
+  spec.add_dependency "puma",     "~> 6.4"
+  spec.add_dependency "rackup",   "~> 2.1"
+
+  # gRPC transport — loaded lazily by Server::GrpcServer so HTTP-only
+  # deployments don't pay the load-time cost.
+  spec.add_dependency "grpc", "~> 1.69"
+  spec.add_dependency "google-protobuf", "~> 4.0"
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake",     "~> 13.0"
+  spec.add_development_dependency "rack-test", "~> 2.1"
+  spec.add_development_dependency "grpc-tools", "~> 1.69"
+end

package/dist/scaffold-repo/sdks/ruby/config.ru

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "lib/blok"
+require_relative "examples/hello_world_node"
+require_relative "examples/api_call_node"
+require_relative "examples/transform_data_node"
+require_relative "examples/chain_test_node"
+
+registry = Blok::Server::RuntimeApp.registry
+registry.register("hello-world", HelloWorldNode.new)
+registry.register("api-call", ApiCallNode.new)
+registry.register("transform-data", TransformDataNode.new)
+registry.register("chain-test", ChainTestNode.new)
+
+run Blok::Server::RuntimeApp

package/dist/scaffold-repo/sdks/ruby/examples/api_call_node.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "../lib/blok"
+require "net/http"
+require "uri"
+require "json"
+
+# ApiCallNode makes HTTP requests to external APIs.
+#
+# Config:
+#   - "url"     (string, required): The URL to call
+#   - "method"  (string, optional): HTTP method (default: "GET")
+#   - "timeout" (integer, optional): Timeout in seconds (default: 10)
+#   - "headers" (hash, optional): Additional request headers
+#
+# Request body:
+#   - "body" (object, optional): Request body for POST/PUT/PATCH
+#
+# Output:
+#   { "status" => 200, "data" => {...}, "headers" => {...} }
+class ApiCallNode < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    url = config["url"]
+    unless url
+      raise Blok::Errors::NodeError.configuration("'url' is required in node config")
+    end
+
+    method  = (config["method"] || "GET").upcase
+    timeout = config["timeout"] || 10
+
+    uri = URI.parse(url)
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl     = uri.scheme == "https"
+    http.open_timeout = timeout
+    http.read_timeout = timeout
+
+    request = build_request(method, uri, ctx, config)
+
+    begin
+      response = http.request(request)
+    rescue StandardError => e
+      raise Blok::Errors::NodeError.network("request to #{url} failed: #{e.message}")
+    end
+
+    body = begin
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+
+    headers = {}
+    response.each_header { |k, v| headers[k] = v }
+
+    {
+      "status"  => response.code.to_i,
+      "data"    => body,
+      "headers" => headers
+    }
+  end
+
+  private
+
+  def build_request(method, uri, ctx, config)
+    klass = case method
+            when "POST"   then Net::HTTP::Post
+            when "PUT"    then Net::HTTP::Put
+            when "PATCH"  then Net::HTTP::Patch
+            when "DELETE" then Net::HTTP::Delete
+            when "HEAD"   then Net::HTTP::Head
+            else               Net::HTTP::Get
+            end
+
+    req = klass.new(uri)
+    req["Content-Type"] = "application/json"
+
+    # Add configured headers
+    if config["headers"].is_a?(Hash)
+      config["headers"].each { |k, v| req[k] = v.to_s }
+    end
+
+    # Attach body for POST/PUT/PATCH
+    if %w[POST PUT PATCH].include?(method) && ctx.request.body.is_a?(Hash)
+      body_data = ctx.request.body["body"]
+      req.body = JSON.generate(body_data) if body_data
+    end
+
+    req
+  end
+end
+
+# ----- Boot the server if run directly -----
+if __FILE__ == $PROGRAM_NAME
+  registry = Blok::Server::RuntimeApp.registry
+  registry.register("api-call", ApiCallNode.new)
+
+  puts "Starting ApiCallNode on port 8080..."
+  Blok::Server::RuntimeApp.run!(port: 8080, bind: "0.0.0.0")
+end

package/dist/scaffold-repo/sdks/ruby/examples/blok_error_demo_node.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../lib/blok"
+
+# Example node demonstrating the structured +Blok::Errors::BlokError+ API per
+# master plan §17.
+#
+# Used by the cross-language E2E test
+# (+core/runner/__tests__/integration/runtimes/ruby-grpc.integration.test.ts+)
+# to verify that a Ruby-side structured error flows through the gRPC wire to
+# the runner with every field preserved (category, severity, code,
+# remediation, retryable hints, cause chain, context snapshot).
+#
+# Triggered via the +mode+ config:
+# - +mode = "dependency"+ (default) — raises +BlokError.dependency+ with a
+#   cause chain rooted in a +SocketError+.
+# - +mode = "rate-limit"+ — raises +BlokError.rate_limit+ with +retry_after_ms+.
+# - +mode = "validation"+ — raises +BlokError.validation+ with +details["issues"]+.
+# - +mode = "ok"+ — returns success.
+class BlokErrorDemoNode < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    mode = config["mode"] || "dependency"
+
+    if mode == "ok"
+      return { "ok" => true, "language" => "ruby" }
+    end
+
+    snapshot = Blok::Errors::BuildContextSnapshot.of(
+      inputs: config,
+      vars: ctx.respond_to?(:vars) ? (ctx.vars || {}) : {}
+    )
+
+    case mode
+    when "rate-limit"
+      raise Blok::Errors::BlokError.rate_limit(
+        code: "UPSTREAM_RATE_LIMITED",
+        message: "Upstream API returned 429",
+        description: "GitHub API rate limit hit (5000 req/hr).",
+        remediation: "Wait until the X-RateLimit-Reset header timestamp.",
+        retry_after_ms: 60_000,
+        doc_url: "https://docs.example.com/errors/rate-limit",
+        details: { "limit" => 5000, "remaining" => 0 },
+        context_snapshot: snapshot
+      )
+    when "validation"
+      raise Blok::Errors::BlokError.validation(
+        code: "VALIDATION_FAILED",
+        message: "2 validation issues",
+        description: "Inputs didn't match the node's schema.",
+        remediation: "Provide both `email` and `name`.",
+        details: {
+          "issues" => [
+            { "path" => ["email"], "message" => "Required" },
+            { "path" => ["name"],  "message" => "Required" }
+          ]
+        },
+        context_snapshot: snapshot
+      )
+    else
+      # default: dependency with a cause chain rooted in a SocketError.
+      begin
+        raise SocketError, "[Errno 61] Connection refused"
+      rescue SocketError => cause
+        raise Blok::Errors::BlokError.dependency(
+          code: "POSTGRES_CONNECT_TIMEOUT",
+          message: "Could not connect to Postgres within 5s",
+          description: "Tried host=db.internal port=5432; timeout=5000ms",
+          remediation: "Check DATABASE_URL env var and network reachability",
+          cause: cause,
+          retryable: true,
+          retry_after_ms: 5_000,
+          doc_url: "https://docs.example.com/errors/POSTGRES_CONNECT_TIMEOUT",
+          details: { "host" => "db.internal", "port" => 5432, "timeout_ms" => 5000 },
+          context_snapshot: snapshot
+        )
+      end
+    end
+  end
+end

package/dist/scaffold-repo/sdks/ruby/examples/chain_test_node.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../lib/blok"
+
+# ChainTestNode is used in cross-runtime integration tests.
+# It reads a chain array from the request body, appends its own entry,
+# and returns the updated chain — proving data flows between languages.
+class ChainTestNode < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    body = ctx.request.body
+
+    # Read existing chain — gRPC inputs first (carried on `node.config`),
+    # HTTP body fallback (legacy wire shape where the runner mapped
+    # resolvedInputs → request.body). Dual-read keeps the
+    # cross-runtime-chain demo working over both transports during the
+    # §11 deprecation window.
+    chain =
+      if config.is_a?(Hash) && config["chain"].is_a?(Array)
+        config["chain"].dup
+      elsif body.is_a?(Hash) && body["chain"].is_a?(Array)
+        body["chain"].dup
+      else
+        []
+      end
+
+    # Read origin — same dual-read.
+    origin =
+      if config.is_a?(Hash) && config["origin"].is_a?(String) && !config["origin"].empty?
+        config["origin"]
+      elsif body.is_a?(Hash) && body["origin"].is_a?(String)
+        body["origin"]
+      else
+        "unknown"
+      end
+
+    # Append this language's entry
+    chain << {
+      "language"  => "ruby",
+      "order"     => chain.length + 1,
+      "timestamp" => Time.now.utc.iso8601
+    }
+
+    # Store in context vars
+    ctx.set_var("chain", chain)
+
+    {
+      "chain"  => chain,
+      "origin" => origin
+    }
+  end
+end

package/dist/scaffold-repo/sdks/ruby/examples/hello_world_node.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../lib/blok"
+
+# HelloWorldNode greets the user with a configurable prefix.
+#
+# Config:
+#   - "prefix" (string, optional): Greeting prefix (default: "Hello")
+#
+# Request body:
+#   - "name" (string, optional): Name to greet (default: "World")
+#
+# Output:
+#   { "message" => "Hello, World!", "timestamp" => "...", "language" => "ruby" }
+class HelloWorldNode < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    name   = ctx.request.body_str("name") || "World"
+    prefix = config["prefix"] || "Hello"
+
+    message = "#{prefix}, #{name}!"
+
+    # Store the greeting in context for downstream nodes
+    ctx.set_var("greeting", message)
+
+    {
+      "message"   => message,
+      "timestamp" => Time.now.utc.iso8601,
+      "language"  => "ruby"
+    }
+  end
+end
+
+# ----- Boot the server if run directly -----
+if __FILE__ == $PROGRAM_NAME
+  registry = Blok::Server::RuntimeApp.registry
+  registry.register("hello-world", HelloWorldNode.new)
+
+  puts "Starting HelloWorldNode on port 8080..."
+  Blok::Server::RuntimeApp.run!(port: 8080, bind: "0.0.0.0")
+end

package/dist/scaffold-repo/sdks/ruby/examples/transform_data_node.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../lib/blok"
+
+# TransformDataNode transforms JSON data based on field mappings.
+#
+# Config:
+#   - "mappings"     (hash, optional): Map of target field -> source field path (dot-notation)
+#   - "include_only" (array, optional): Only include these fields in output
+#   - "exclude"      (array, optional): Exclude these fields from output
+#   - "defaults"     (hash, optional): Default values for missing fields
+#
+# Input: Request body (must be a JSON object)
+# Output: Transformed JSON object
+class TransformDataNode < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    body = ctx.request.body
+    unless body.is_a?(Hash)
+      raise Blok::Errors::NodeError.validation("request body must be a JSON object")
+    end
+
+    result = {}
+
+    # Apply field mappings if configured
+    if config["mappings"].is_a?(Hash)
+      config["mappings"].each do |target, source_path|
+        next unless source_path.is_a?(String)
+
+        value = get_nested_value(body, source_path)
+        result[target] = value unless value.nil?
+      end
+    else
+      # No mappings -- copy all fields
+      body.each { |k, v| result[k] = v }
+    end
+
+    # Apply include_only filter
+    if config["include_only"].is_a?(Array)
+      allowed = config["include_only"]
+      result.select! { |k, _| allowed.include?(k) }
+    end
+
+    # Apply exclude filter
+    if config["exclude"].is_a?(Array)
+      config["exclude"].each { |field| result.delete(field) }
+    end
+
+    # Apply defaults for missing fields
+    if config["defaults"].is_a?(Hash)
+      config["defaults"].each do |k, v|
+        result[k] = v unless result.key?(k)
+      end
+    end
+
+    # Store in context for downstream nodes
+    ctx.set_var("transformed_data", result)
+
+    result
+  end
+
+  private
+
+  # Traverse dot-notation path (e.g. "user.name") into nested hashes.
+  def get_nested_value(data, path)
+    current = data
+    path.split(".").each do |part|
+      return nil unless current.is_a?(Hash)
+
+      current = current[part]
+    end
+    current
+  end
+end
+
+# ----- Boot the server if run directly -----
+if __FILE__ == $PROGRAM_NAME
+  registry = Blok::Server::RuntimeApp.registry
+  registry.register("transform-data", TransformDataNode.new)
+
+  puts "Starting TransformDataNode on port 8080..."
+  Blok::Server::RuntimeApp.run!(port: 8080, bind: "0.0.0.0")
+end

package/dist/scaffold-repo/sdks/ruby/examples/typed_greet_node.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../lib/blok"
+
+# Typed greeting node demonstrating the SPEC-B TypedNode contract.
+class TypedGreetNode < Blok::Node::TypedNode
+  node_name "typed-greet"
+  description "Typed greeting (SPEC-B contract demo)"
+
+  input do
+    field :name, :string, required: true
+    field :repeat, :integer, default: 1
+  end
+
+  output do
+    field :greeting, :string
+    field :length, :integer
+  end
+
+  def run(_ctx, input)
+    repeat = input[:repeat].is_a?(Integer) && input[:repeat].positive? ? input[:repeat] : 1
+    greeting = ("Hello, " + input[:name]) * repeat
+    { "greeting" => greeting, "length" => greeting.length }
+  end
+end