blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/sdks/go/proto/blok/runtime/v1/runtime.proto

@@ -0,0 +1,302 @@
+// Blok Runtime v1 — the wire contract between the TypeScript runner and SDK
+// servers (Python, Go, Rust, Java, C#, PHP, Ruby).
+//
+// Single source of truth for cross-language interop. Generated stubs in each
+// SDK are derived from this file via `make proto`.
+//
+// Stability: `blok.runtime.v1` is additive-only. CI runs `buf breaking` to
+// reject backward-incompatible changes. Breaking changes go to `v2`, served
+// alongside `v1` during migration.
+
+syntax = "proto3";
+
+package blok.runtime.v1;
+
+option go_package          = "github.com/nickincloud/blok-go/genpb/blok/runtime/v1;runtimev1";
+option java_package        = "com.blok.runtime.v1";
+option java_multiple_files = true;
+option csharp_namespace    = "Blok.Runtime.V1";
+option php_namespace       = "Blok\\Runtime\\V1";
+option ruby_package        = "Blok::Runtime::V1";
+
+import "google/protobuf/timestamp.proto";
+
+// =============================================================================
+// Service
+// =============================================================================
+
+// NodeRuntime is the contract every Blok SDK exposes. One service handles
+// three responsibilities:
+//   1. Run a node (Execute / ExecuteStream)
+//   2. Tell the runner which nodes it can run (ListNodes)
+//   3. Tell the runner if it is alive (Health)
+service NodeRuntime {
+  // Run a node and return its result. Unary, deadline-driven.
+  rpc Execute       (ExecuteRequest)   returns (ExecuteResponse);
+
+  // Run a node and stream events back as it executes (logs, progress, partial
+  // results, then a final ExecuteResponse). Optional capability — SDKs that
+  // don't implement it should return UNIMPLEMENTED.
+  rpc ExecuteStream (ExecuteRequest)   returns (stream ExecuteEvent);
+
+  // Health check (wire-compatible with grpc.health.v1.Health/Check).
+  rpc Health        (HealthRequest)    returns (HealthResponse);
+
+  // Discover registered nodes and their schemas (drives Studio + OpenAPI gen).
+  rpc ListNodes     (ListNodesRequest) returns (ListNodesResponse);
+}
+
+// =============================================================================
+// Execute envelope (the "what we send to a node")
+// =============================================================================
+
+message ExecuteRequest {
+  // Identification: which node, what type, what version.
+  NodeRef        node     = 1;
+
+  // The node's own resolved inputs. Already mapped (js/, ${...} resolved).
+  // Bytes-encoded JSON: SDKs JSON-decode lazily. NEVER wrapped in {inputs:...}.
+  bytes          inputs   = 2;
+
+  // Where in the workflow this node sits.
+  StepInfo       step     = 3;
+
+  // The originating workflow trigger (read-only context for nodes).
+  TriggerInfo    trigger  = 4;
+
+  // Mutable state: previous step output, persistent vars, env mirror.
+  RuntimeState   state    = 5;
+
+  // Identity of the parent workflow run.
+  WorkflowInfo   workflow = 6;
+
+  // Per-call options (deadline, streaming opt-in).
+  ExecuteOptions options  = 7;
+}
+
+message NodeRef {
+  string name    = 1;   // e.g. "tutorial-store"
+  string type    = 2;   // "runtime.python3"
+  string version = 3;   // optional pin, e.g. "1.0.0"
+}
+
+message StepInfo {
+  string name  = 1;     // step name in workflow
+  int32  index = 2;     // 0-based index in current branch
+  int32  total = 3;     // total steps in current branch
+  int32  depth = 4;     // 0 = top-level; 1+ = nested in flow node (if-else)
+}
+
+message TriggerInfo {
+  // Snapshot of the trigger that started the workflow. Read-only for nodes.
+  bytes  body          = 1;            // raw bytes; encoding signaled in headers
+  map<string, string> headers = 2;
+  map<string, string> params  = 3;
+  map<string, string> query   = 4;
+  map<string, string> cookies = 5;
+  string method        = 6;
+  string url           = 7;
+  string base_url      = 8;
+  string trigger_kind  = 9;            // "http" | "worker" | "cron" | ...
+}
+
+message RuntimeState {
+  // Output of the previous step. Named explicitly so LLM-authored nodes stop
+  // confusing it with vars. Bytes-encoded JSON.
+  bytes  previous_output = 1;
+
+  // Workflow-scoped persistent storage (set_var: true on prior steps).
+  // Bytes-encoded JSON map<string, any>.
+  bytes  vars            = 2;
+
+  // String→string env mirror.
+  map<string, string> env = 3;
+}
+
+message WorkflowInfo {
+  string run_id   = 1;
+  string name     = 2;
+  string path     = 3;
+  string version  = 4;
+  google.protobuf.Timestamp started_at = 5;
+}
+
+message ExecuteOptions {
+  int64 deadline_ms     = 1;       // hard cutoff (also enforced via gRPC deadline)
+  bool  stream_logs     = 2;       // hint: caller wants ExecuteStream events
+  bool  capture_metrics = 3;
+  // Reserved for future routing/affinity hints without bumping schema.
+  map<string, string> hints = 15;
+}
+
+// =============================================================================
+// Execute response
+// =============================================================================
+
+message ExecuteResponse {
+  bool      success      = 1;
+
+  // The node's primary return value. Bytes-encoded JSON.
+  bytes     data         = 2;
+
+  // Optional content-type override (default "application/json").
+  string    content_type = 3;
+
+  // Set iff !success. Always populated on failure (see NodeError).
+  NodeError error        = 4;
+
+  // Vars the node wants persisted (merged into ctx.vars on the runner side).
+  // Optional — most nodes leave this empty and rely on workflow-level set_var.
+  // Bytes-encoded JSON map<string, any>.
+  bytes     vars_delta   = 5;
+
+  // Tail of logs captured during execution.
+  repeated  LogLine logs = 6;
+
+  // Resource usage during this call. Populated when capture_metrics=true.
+  Metrics   metrics      = 7;
+}
+
+// =============================================================================
+// Streaming variant (Phase 5 — opt-in)
+// =============================================================================
+
+message ExecuteEvent {
+  oneof event {
+    NodeStarted     started  = 1;
+    LogLine         log      = 2;
+    Progress        progress = 3;
+    PartialResult   partial  = 4;
+    ExecuteResponse final    = 5;   // last frame; closes the stream
+  }
+}
+
+message NodeStarted   { google.protobuf.Timestamp at = 1; }
+message Progress      { double percent = 1; string phase = 2; }
+message PartialResult { bytes snapshot_json = 1; }
+
+message LogLine {
+  google.protobuf.Timestamp timestamp = 1;
+  string level    = 2;            // "debug" | "info" | "warn" | "error"
+  string message  = 3;
+  map<string, string> attributes = 4;
+}
+
+// =============================================================================
+// NodeError — the structured-errors contract
+// =============================================================================
+//
+// Every node in every SDK populates a NodeError the same way. Seven required
+// fields (code, category, severity, node, at, message, http_status) plus
+// strongly-encouraged fields for richer debugging:
+// - description: multi-paragraph context (what was tried, why it failed)
+// - remediation: suggested next step (actionable)
+// - context_snapshot_json: bounded slice of inputs/state at error time
+// - causes: nested wrapped errors (e.g. an HTTP error wrapping a timeout)
+//
+// SDKs auto-fill `node`, `sdk`, `sdk_version`, `runtime_kind`, `at`, and
+// `stack` from environmental context — authors never set these manually.
+//
+// See `docs/error-codes.md` for the canonical code registry.
+
+message NodeError {
+  // === Identity ===
+  string        code        = 1;       // STABLE machine identifier (e.g. "POSTGRES_CONNECT_TIMEOUT")
+  ErrorCategory category    = 2;
+  ErrorSeverity severity    = 3;
+
+  // === Origin (auto-filled by SDK) ===
+  string        node          = 4;
+  string        sdk           = 5;     // "blok-python3"
+  string        sdk_version   = 6;
+  string        runtime_kind  = 7;     // "runtime.python3"
+  google.protobuf.Timestamp at = 8;
+
+  // === Human-readable ===
+  string        message     = 9;       // one-sentence summary
+  string        description = 10;      // multi-paragraph context
+  string        remediation = 11;      // suggested next step
+  string        doc_url     = 12;
+
+  // === Causality ===
+  repeated NodeError causes = 13;
+  string             stack  = 14;
+  bytes              context_snapshot_json = 15;
+
+  // === Compatibility / retry hints ===
+  int32  http_status     = 16;
+  bool   retryable       = 17;
+  int64  retry_after_ms  = 18;
+
+  // === Category-specific structured details ===
+  // Bytes-encoded JSON. Surfaces to GlobalError.json on the runner side.
+  bytes  details_json = 19;
+}
+
+enum ErrorCategory {
+  CATEGORY_UNSPECIFIED = 0;
+  VALIDATION    = 1;   // input/output schema mismatch
+  CONFIGURATION = 2;   // node misconfigured
+  DEPENDENCY    = 3;   // external service failed (DB, HTTP, queue)
+  TIMEOUT       = 4;
+  PERMISSION    = 5;   // auth/authz
+  RATE_LIMIT    = 6;
+  NOT_FOUND     = 7;
+  CONFLICT      = 8;
+  CANCELLED     = 9;
+  INTERNAL      = 10;  // unexpected SDK-side bug
+  PROTOCOL      = 11;  // proto/transport issue
+  DATA          = 12;  // user data malformed (not schema validation)
+}
+
+enum ErrorSeverity {
+  SEVERITY_UNSPECIFIED = 0;
+  INFO  = 1;   // expected, recoverable
+  WARN  = 2;   // anomalous but workflow continues
+  ERROR = 3;   // node failed; default
+  FATAL = 4;   // workflow should abort regardless of try/catch
+}
+
+// =============================================================================
+// Discovery
+// =============================================================================
+
+message ListNodesRequest {}
+message ListNodesResponse {
+  repeated NodeDescriptor nodes = 1;
+  string sdk_name      = 2;          // "blok-python3"
+  string sdk_version   = 3;
+  string proto_version = 4;          // "1.0.0"
+}
+
+message NodeDescriptor {
+  string name        = 1;
+  string description = 2;
+  bytes  input_schema_json  = 3;     // JSON Schema (drives OpenAPI/Studio/LLMs)
+  bytes  output_schema_json = 4;
+  repeated string tags = 5;
+}
+
+// =============================================================================
+// Health (wire-compatible with grpc.health.v1)
+// =============================================================================
+
+message HealthRequest  { string service = 1; }
+message HealthResponse {
+  enum Status { UNKNOWN = 0; SERVING = 1; NOT_SERVING = 2; }
+  Status status      = 1;
+  string sdk_version = 2;
+  repeated string registered_nodes = 3;
+}
+
+// =============================================================================
+// Metrics
+// =============================================================================
+
+message Metrics {
+  double duration_ms    = 1;
+  double cpu_ms         = 2;
+  int64  memory_bytes   = 3;
+  int64  request_bytes  = 4;
+  int64  response_bytes = 5;
+}

package/dist/scaffold-repo/sdks/go/registry.go

@@ -0,0 +1,156 @@
+package blok
+
+import (
+	"fmt"
+	"runtime"
+	"sync"
+	"time"
+)
+
+// NodeRegistry manages registered node handlers and executes them.
+type NodeRegistry struct {
+	mu         sync.RWMutex
+	nodes      map[string]NodeHandler
+	middleware []Middleware
+	validator  *SchemaValidator
+}
+
+// NewNodeRegistry creates a new node registry.
+func NewNodeRegistry() *NodeRegistry {
+	return &NodeRegistry{
+		nodes:     make(map[string]NodeHandler),
+		validator: NewSchemaValidator(),
+	}
+}
+
+// Register registers a node handler with the given name.
+func (r *NodeRegistry) Register(name string, handler NodeHandler) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.nodes[name] = handler
+}
+
+// Use adds middleware to the registry. Middleware is applied to all node
+// executions in the order added.
+func (r *NodeRegistry) Use(mw ...Middleware) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.middleware = append(r.middleware, mw...)
+}
+
+// Get retrieves a node handler by name.
+func (r *NodeRegistry) Get(name string) (NodeHandler, error) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	handler, exists := r.nodes[name]
+	if !exists {
+		return nil, NewNotFoundError(fmt.Sprintf("node '%s' not found", name))
+	}
+	return handler, nil
+}
+
+// NodeNames returns the names of all registered nodes.
+func (r *NodeRegistry) NodeNames() []string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	names := make([]string, 0, len(r.nodes))
+	for name := range r.nodes {
+		names = append(names, name)
+	}
+	return names
+}
+
+// Execute executes a node by name with the given request.
+// It applies all registered middleware and captures metrics.
+func (r *NodeRegistry) Execute(req *ExecutionRequest) *ExecutionResult {
+	start := time.Now()
+	var memBefore uint64
+	var memStats runtime.MemStats
+	runtime.ReadMemStats(&memStats)
+	memBefore = memStats.Alloc
+
+	// Look up handler
+	handler, err := r.Get(req.Node.Name)
+	if err != nil {
+		return NewErrorResult(err.Error())
+	}
+
+	// Apply middleware chain
+	r.mu.RLock()
+	middlewares := make([]Middleware, len(r.middleware))
+	copy(middlewares, r.middleware)
+	r.mu.RUnlock()
+
+	if len(middlewares) > 0 {
+		handler = Chain(middlewares...)(handler)
+	}
+
+	// Execute
+	data, err := handler.Execute(&req.Context, req.Node.Config)
+
+	// Calculate metrics
+	duration := time.Since(start)
+	runtime.ReadMemStats(&memStats)
+	memAfter := memStats.Alloc
+	var memUsed uint64
+	if memAfter > memBefore {
+		memUsed = memAfter - memBefore
+	}
+
+	durationMs := float64(duration.Microseconds()) / 1000.0
+
+	if err != nil {
+		errResult := &ExecutionResult{
+			Success: false,
+			Data:    nil,
+			Metrics: &ExecutionMetrics{
+				DurationMs:  Float64Ptr(durationMs),
+				MemoryBytes: Uint64Ptr(memUsed),
+			},
+		}
+
+		// 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.
+		if blokErr, ok := err.(*BlokError); ok {
+			errResult.Errors = blokErr
+		} else if nodeErr, ok := err.(*NodeError); ok {
+			errResult.Errors = nodeErr.ToMap()
+		} else {
+			errResult.Errors = map[string]string{
+				"message": err.Error(),
+			}
+		}
+
+		return errResult
+	}
+
+	result := &ExecutionResult{
+		Success: true,
+		Data:    data,
+		Errors:  nil,
+		Metrics: &ExecutionMetrics{
+			DurationMs:  Float64Ptr(durationMs),
+			MemoryBytes: Uint64Ptr(memUsed),
+		},
+	}
+
+	// Include context vars so the runner can propagate them downstream
+	if len(req.Context.Vars) > 0 {
+		result.Vars = req.Context.Vars
+	}
+
+	return result
+}
+
+// Health returns the health status of the registry.
+func (r *NodeRegistry) Health(version string) *HealthStatus {
+	return &HealthStatus{
+		Status:      "healthy",
+		Version:     version,
+		NodesLoaded: r.NodeNames(),
+	}
+}

package/dist/scaffold-repo/sdks/go/registry_test.go

@@ -0,0 +1,195 @@
+package blok
+
+import (
+	"errors"
+	"testing"
+)
+
+// testNode is a simple node handler for tests.
+type testNode struct {
+	returnData  interface{}
+	returnError error
+}
+
+func (n *testNode) Execute(ctx *Context, config map[string]interface{}) (interface{}, error) {
+	return n.returnData, n.returnError
+}
+
+func TestNodeRegistryRegisterAndGet(t *testing.T) {
+	registry := NewNodeRegistry()
+	handler := &testNode{returnData: "hello"}
+
+	registry.Register("test-node", handler)
+
+	got, err := registry.Get("test-node")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got == nil {
+		t.Fatal("expected non-nil handler")
+	}
+}
+
+func TestNodeRegistryGetNotFound(t *testing.T) {
+	registry := NewNodeRegistry()
+
+	_, err := registry.Get("nonexistent")
+	if err == nil {
+		t.Fatal("expected error for nonexistent node")
+	}
+
+	var nodeErr *NodeError
+	if !errors.As(err, &nodeErr) {
+		t.Fatalf("expected NodeError, got %T", err)
+	}
+	if nodeErr.Category != ErrorCategoryNotFound {
+		t.Errorf("expected NOT_FOUND category, got %v", nodeErr.Category)
+	}
+}
+
+func TestNodeRegistryExecuteSuccess(t *testing.T) {
+	registry := NewNodeRegistry()
+	registry.Register("test-node", &testNode{
+		returnData: map[string]string{"message": "hello"},
+	})
+
+	result := registry.Execute(&ExecutionRequest{
+		Node: NodeConfig{
+			Name:   "test-node",
+			Config: map[string]interface{}{},
+		},
+		Context: NewMockContext().Build(),
+	})
+
+	if !result.Success {
+		t.Errorf("expected success, got errors: %v", result.Errors)
+	}
+	if result.Data == nil {
+		t.Error("expected non-nil data")
+	}
+	if result.Metrics == nil {
+		t.Error("expected non-nil metrics")
+	}
+	if result.Metrics.DurationMs == nil {
+		t.Error("expected duration_ms to be set")
+	}
+}
+
+func TestNodeRegistryExecuteError(t *testing.T) {
+	registry := NewNodeRegistry()
+	registry.Register("error-node", &testNode{
+		returnError: errors.New("execution failed"),
+	})
+
+	result := registry.Execute(&ExecutionRequest{
+		Node: NodeConfig{
+			Name:   "error-node",
+			Config: map[string]interface{}{},
+		},
+		Context: NewMockContext().Build(),
+	})
+
+	if result.Success {
+		t.Error("expected failure")
+	}
+	if result.Errors == nil {
+		t.Error("expected non-nil errors")
+	}
+}
+
+func TestNodeRegistryExecuteNodeNotFound(t *testing.T) {
+	registry := NewNodeRegistry()
+
+	result := registry.Execute(&ExecutionRequest{
+		Node: NodeConfig{
+			Name:   "missing-node",
+			Config: map[string]interface{}{},
+		},
+		Context: NewMockContext().Build(),
+	})
+
+	if result.Success {
+		t.Error("expected failure")
+	}
+}
+
+func TestNodeRegistryNodeNames(t *testing.T) {
+	registry := NewNodeRegistry()
+	registry.Register("node-a", &testNode{})
+	registry.Register("node-b", &testNode{})
+	registry.Register("node-c", &testNode{})
+
+	names := registry.NodeNames()
+	if len(names) != 3 {
+		t.Errorf("expected 3 names, got %d", len(names))
+	}
+
+	nameSet := make(map[string]bool)
+	for _, n := range names {
+		nameSet[n] = true
+	}
+	for _, expected := range []string{"node-a", "node-b", "node-c"} {
+		if !nameSet[expected] {
+			t.Errorf("missing node name: %s", expected)
+		}
+	}
+}
+
+func TestNodeRegistryHealth(t *testing.T) {
+	registry := NewNodeRegistry()
+	registry.Register("hello-world", &testNode{})
+	registry.Register("api-call", &testNode{})
+
+	health := registry.Health("2.0.0")
+
+	if health.Status != "healthy" {
+		t.Errorf("expected 'healthy', got %q", health.Status)
+	}
+	if health.Version != "2.0.0" {
+		t.Errorf("expected '2.0.0', got %q", health.Version)
+	}
+	if len(health.NodesLoaded) != 2 {
+		t.Errorf("expected 2 nodes, got %d", len(health.NodesLoaded))
+	}
+}
+
+func TestNodeRegistryExecuteWithNodeError(t *testing.T) {
+	registry := NewNodeRegistry()
+	registry.Register("validation-node", &testNode{
+		returnError: NewValidationError("invalid input"),
+	})
+
+	result := registry.Execute(&ExecutionRequest{
+		Node: NodeConfig{
+			Name:   "validation-node",
+			Config: map[string]interface{}{},
+		},
+		Context: NewMockContext().Build(),
+	})
+
+	if result.Success {
+		t.Error("expected failure")
+	}
+
+	errMap, ok := result.Errors.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected map[string]interface{}, got %T", result.Errors)
+	}
+	if errMap["category"] != "VALIDATION" {
+		t.Errorf("expected VALIDATION category, got %v", errMap["category"])
+	}
+}
+
+func TestNodeHandlerFunc(t *testing.T) {
+	handler := NodeHandlerFunc(func(ctx *Context, config map[string]interface{}) (interface{}, error) {
+		return "hello from func", nil
+	})
+
+	data, err := handler.Execute(&Context{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if data != "hello from func" {
+		t.Errorf("expected 'hello from func', got %v", data)
+	}
+}