blokctl 1.3.0 → 1.4.1

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

@@ -0,0 +1,433 @@
+// Unit tests for the structured BlokError per master plan §17.
+//
+// Mirrors the Python suite in sdks/python3/tests/test_blok_error.py.
+// Covers all 12 category factories, builder option overrides, FromUnknown
+// heuristics, ToMap/FromMap round-trip, cause chain flattening (cycle-safe),
+// and BuildContextSnapshot byte-budget trimming.
+
+package blok
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+)
+
+// =============================================================================
+// Factories
+// =============================================================================
+
+func TestFactory_AllCategoriesSetCorrectDefaults(t *testing.T) {
+	cases := []struct {
+		category   ErrorCategory
+		httpStatus int
+		retryable  bool
+	}{
+		{CategoryValidation, 400, false},
+		{CategoryConfiguration, 500, false},
+		{CategoryDependency, 502, true},
+		{CategoryTimeout, 504, true},
+		{CategoryPermission, 403, false},
+		{CategoryRateLimit, 429, true},
+		{CategoryNotFound, 404, false},
+		{CategoryConflict, 409, false},
+		{CategoryCancelled, 499, false},
+		{CategoryInternal, 500, false},
+		{CategoryProtocol, 502, false},
+		{CategoryData, 422, false},
+	}
+	for _, c := range cases {
+		t.Run(string(c.category), func(t *testing.T) {
+			err := NewError(c.category).Code("TEST").Message("m").Build()
+			if err.Category != c.category {
+				t.Errorf("category mismatch: got %s want %s", err.Category, c.category)
+			}
+			if err.HTTPStatus != c.httpStatus {
+				t.Errorf("http_status: got %d want %d", err.HTTPStatus, c.httpStatus)
+			}
+			if err.Retryable != c.retryable {
+				t.Errorf("retryable: got %v want %v", err.Retryable, c.retryable)
+			}
+			if err.Severity != SeverityError {
+				t.Errorf("severity: got %s want ERROR", err.Severity)
+			}
+		})
+	}
+}
+
+func TestBuilder_OptionsOverrideDefaults(t *testing.T) {
+	cause := errors.New("underlying")
+	err := NewError(CategoryDependency).
+		Code("POSTGRES_DOWN").
+		Message("db down").
+		Description("long story").
+		Remediation("restart it").
+		DocURL("https://example.com/x").
+		Retryable(false).
+		RetryAfter(10 * time.Second).
+		Details(map[string]interface{}{"sql_state": "08001"}).
+		HTTPStatus(503).
+		Severity(SeverityFatal).
+		Cause(cause).
+		Build()
+
+	if err.Retryable {
+		t.Error("Retryable should override default true")
+	}
+	if err.HTTPStatus != 503 {
+		t.Errorf("HTTPStatus: got %d want 503", err.HTTPStatus)
+	}
+	if err.Severity != SeverityFatal {
+		t.Errorf("Severity: got %s want FATAL", err.Severity)
+	}
+	if err.Description != "long story" || err.Remediation != "restart it" || err.DocURL != "https://example.com/x" {
+		t.Error("description/remediation/docurl not set")
+	}
+	if err.RetryAfterMs != 10_000 {
+		t.Errorf("RetryAfterMs: got %d want 10000", err.RetryAfterMs)
+	}
+	if d, ok := err.Details.(map[string]interface{}); !ok || d["sql_state"] != "08001" {
+		t.Errorf("Details mismatch: %#v", err.Details)
+	}
+	if !errors.Is(err, cause) {
+		t.Error("errors.Is should traverse to underlying cause")
+	}
+}
+
+func TestBuilder_AtIsUTC(t *testing.T) {
+	err := NewError(CategoryInternal).Code("X").Message("m").Build()
+	if err.At.Location() != time.UTC {
+		t.Errorf("expected UTC time, got %s", err.At.Location())
+	}
+	if time.Since(err.At) > 5*time.Second {
+		t.Errorf("At too old: %s", err.At)
+	}
+}
+
+func TestBuilder_StackIsCaptured(t *testing.T) {
+	err := NewError(CategoryInternal).Code("X").Message("m").Build()
+	if err.Stack == "" {
+		t.Error("expected non-empty Stack")
+	}
+}
+
+// =============================================================================
+// FromUnknown heuristics
+// =============================================================================
+
+func TestFromUnknown_PassesThroughBlokError(t *testing.T) {
+	original := NewError(CategoryDependency).Code("X").Message("m").Build()
+	wrapped := FromUnknown(original, Origin{})
+	if wrapped != original {
+		t.Errorf("expected passthrough, got new instance")
+	}
+}
+
+func TestFromUnknown_EnrichesMissingOriginFields(t *testing.T) {
+	original := NewError(CategoryDependency).Code("X").Message("m").Build()
+	wrapped := FromUnknown(original, Origin{Node: "step-x", SDK: "blok-go", SDKVersion: "1.0.0", RuntimeKind: "runtime.go"})
+	if wrapped.Node != "step-x" || wrapped.SDK != "blok-go" || wrapped.SDKVersion != "1.0.0" || wrapped.RuntimeKind != "runtime.go" {
+		t.Errorf("origin not enriched: %#v", wrapped)
+	}
+}
+
+func TestFromUnknown_DoesNotOverwriteExplicitOriginFields(t *testing.T) {
+	original := NewError(CategoryDependency).Code("X").Message("m").Node("explicit").Build()
+	wrapped := FromUnknown(original, Origin{Node: "from-ctx"})
+	if wrapped.Node != "explicit" {
+		t.Errorf("Node was overwritten: got %q", wrapped.Node)
+	}
+}
+
+func TestFromUnknown_WrapsGoErrorWithUncaughtTypeName(t *testing.T) {
+	wrapped := FromUnknown(errors.New("bad number"), Origin{})
+	if wrapped.Category != CategoryInternal {
+		t.Errorf("expected INTERNAL, got %s", wrapped.Category)
+	}
+	if !strings.HasPrefix(wrapped.Code, "UNCAUGHT_") {
+		t.Errorf("expected UNCAUGHT_* code, got %s", wrapped.Code)
+	}
+	if wrapped.Message != "bad number" {
+		t.Errorf("message: got %q", wrapped.Message)
+	}
+	if len(wrapped.Causes) == 0 {
+		t.Error("cause chain should have at least one entry")
+	}
+}
+
+func TestFromUnknown_WrapsLegacyNodeError(t *testing.T) {
+	legacy := NewExecutionError("legacy boom", errors.New("inner"))
+	wrapped := FromUnknown(legacy, Origin{})
+	if wrapped.Category != CategoryInternal {
+		t.Errorf("expected INTERNAL, got %s", wrapped.Category)
+	}
+	if wrapped.Message != "legacy boom" {
+		t.Errorf("message: got %q", wrapped.Message)
+	}
+	d, ok := wrapped.Details.(map[string]interface{})
+	if !ok {
+		t.Fatalf("Details should be a map: %#v", wrapped.Details)
+	}
+	if d["category"] != "EXECUTION" {
+		t.Errorf("legacy category not preserved: %#v", d)
+	}
+}
+
+func TestFromUnknown_WrapsMapExtractingMessage(t *testing.T) {
+	wrapped := FromUnknown(map[string]interface{}{"message": "boom", "extra": 42}, Origin{})
+	if wrapped.Code != "UNCAUGHT_ERROR" {
+		t.Errorf("expected UNCAUGHT_ERROR, got %s", wrapped.Code)
+	}
+	if wrapped.Message != "boom" {
+		t.Errorf("message: got %q", wrapped.Message)
+	}
+}
+
+func TestFromUnknown_WrapsMapWithoutMessageUsesPlaceholder(t *testing.T) {
+	wrapped := FromUnknown(map[string]interface{}{"only": "fields"}, Origin{})
+	if wrapped.Message != "node error" {
+		t.Errorf("expected placeholder, got %q", wrapped.Message)
+	}
+}
+
+func TestFromUnknown_WrapsMapStringString(t *testing.T) {
+	wrapped := FromUnknown(map[string]string{"message": "boom"}, Origin{})
+	if wrapped.Message != "boom" {
+		t.Errorf("got %q", wrapped.Message)
+	}
+}
+
+func TestFromUnknown_WrapsString(t *testing.T) {
+	wrapped := FromUnknown("plain", Origin{})
+	if wrapped.Message != "plain" {
+		t.Errorf("got %q", wrapped.Message)
+	}
+	d, ok := wrapped.Details.(map[string]interface{})
+	if !ok || d["message"] != "plain" {
+		t.Errorf("Details: %#v", wrapped.Details)
+	}
+}
+
+func TestFromUnknown_WrapsNil(t *testing.T) {
+	wrapped := FromUnknown(nil, Origin{})
+	if wrapped.Code != "UNCAUGHT_ERROR" || wrapped.Message != "node error" {
+		t.Errorf("unexpected wrap: %#v", wrapped)
+	}
+}
+
+// =============================================================================
+// ToMap / FromMap round-trip
+// =============================================================================
+
+func TestToMap_EmitsProtoWireShape(t *testing.T) {
+	err := NewError(CategoryDependency).
+		Code("POSTGRES_DOWN").
+		Message("db down").
+		Description("long story").
+		Remediation("restart it").
+		Retryable(true).
+		RetryAfterMs(5_000).
+		Details(map[string]interface{}{"sql_state": "08001"}).
+		Node("step-1").
+		SDK("blok-go").
+		SDKVersion("1.0.0").
+		RuntimeKind("runtime.go").
+		Build()
+
+	m := err.ToMap()
+	if m["code"] != "POSTGRES_DOWN" {
+		t.Errorf("code: %v", m["code"])
+	}
+	if m["category"] != "DEPENDENCY" {
+		t.Errorf("category: %v", m["category"])
+	}
+	if m["http_status"] != 502 {
+		t.Errorf("http_status: %v", m["http_status"])
+	}
+	if m["retryable"] != true {
+		t.Errorf("retryable: %v", m["retryable"])
+	}
+	if _, ok := m["at"].(string); !ok {
+		t.Errorf("at should be string: %#v", m["at"])
+	}
+}
+
+func TestFromMap_RoundTripsFullPayload(t *testing.T) {
+	original := NewError(CategoryDependency).
+		Code("POSTGRES_DOWN").
+		Message("db down").
+		Description("long story").
+		Remediation("restart it").
+		Retryable(false).
+		RetryAfterMs(5_000).
+		Details(map[string]interface{}{"sql_state": "08001"}).
+		HTTPStatus(503).
+		Node("step-1").
+		Build()
+
+	// Round-trip via JSON to simulate cross-language transport.
+	encoded, err := json.Marshal(original.ToMap())
+	if err != nil {
+		t.Fatal(err)
+	}
+	var decoded map[string]interface{}
+	if err := json.Unmarshal(encoded, &decoded); err != nil {
+		t.Fatal(err)
+	}
+
+	rebuilt := FromMap(decoded)
+	if rebuilt.Category != CategoryDependency {
+		t.Errorf("category: %s", rebuilt.Category)
+	}
+	if rebuilt.Code != "POSTGRES_DOWN" {
+		t.Errorf("code: %s", rebuilt.Code)
+	}
+	if rebuilt.Message != "db down" {
+		t.Errorf("message: %s", rebuilt.Message)
+	}
+	if rebuilt.Description != "long story" {
+		t.Errorf("description: %s", rebuilt.Description)
+	}
+	if rebuilt.HTTPStatus != 503 {
+		t.Errorf("http_status: %d", rebuilt.HTTPStatus)
+	}
+	if rebuilt.RetryAfterMs != 5_000 {
+		t.Errorf("retry_after_ms: %d", rebuilt.RetryAfterMs)
+	}
+}
+
+func TestFromMap_HandlesCamelCaseAndUnknownCategories(t *testing.T) {
+	payload := map[string]interface{}{
+		"code":            "X",
+		"category":        "weird-category", // → INTERNAL fallback
+		"severity":        "huh",            // → ERROR fallback
+		"message":         "m",
+		"httpStatus":      418,
+		"retryAfterMs":    int64(1000),
+		"sdkVersion":      "9.9.9",
+		"runtimeKind":     "runtime.go",
+		"docUrl":          "https://example.com",
+		"contextSnapshot": map[string]interface{}{"x": 1},
+	}
+	err := FromMap(payload)
+	if err.Category != CategoryInternal {
+		t.Errorf("category: %s", err.Category)
+	}
+	if err.Severity != SeverityError {
+		t.Errorf("severity: %s", err.Severity)
+	}
+	if err.HTTPStatus != 418 {
+		t.Errorf("http_status: %d", err.HTTPStatus)
+	}
+	if err.SDKVersion != "9.9.9" {
+		t.Errorf("sdk_version: %s", err.SDKVersion)
+	}
+	if err.DocURL != "https://example.com" {
+		t.Errorf("doc_url: %s", err.DocURL)
+	}
+}
+
+// =============================================================================
+// Cause chain
+// =============================================================================
+
+func TestCauseChain_WrapsPlainError(t *testing.T) {
+	err := NewError(CategoryDependency).
+		Code("X").
+		Message("outer").
+		Cause(errors.New("inner")).
+		Build()
+	if len(err.Causes) != 1 {
+		t.Fatalf("expected 1 cause, got %d", len(err.Causes))
+	}
+	if err.Causes[0]["message"] != "inner" {
+		t.Errorf("cause message: %v", err.Causes[0]["message"])
+	}
+}
+
+func TestCauseChain_BlokErrorAsCauseFlattens(t *testing.T) {
+	leaf := NewError(CategoryDependency).
+		Code("LEAF").
+		Message("leaf").
+		Cause(errors.New("root")).
+		Build()
+	middle := NewError(CategoryDependency).
+		Code("MID").
+		Message("mid").
+		Cause(leaf).
+		Build()
+
+	// `middle.Causes` should contain leaf's payload + leaf's flattened causes,
+	// NOT a single nested cause object with cause inside cause.
+	if len(middle.Causes) != 2 {
+		t.Fatalf("expected 2 flat causes, got %d", len(middle.Causes))
+	}
+	if middle.Causes[0]["code"] != "LEAF" {
+		t.Errorf("first cause code: %v", middle.Causes[0]["code"])
+	}
+	if c, ok := middle.Causes[0]["causes"].([]interface{}); !ok || len(c) != 0 {
+		t.Errorf("nested cause list should be empty: %#v", middle.Causes[0]["causes"])
+	}
+}
+
+// =============================================================================
+// BuildContextSnapshot
+// =============================================================================
+
+func TestBuildContextSnapshot_EmptyInputsAndVars(t *testing.T) {
+	snap := BuildContextSnapshot(map[string]interface{}{}, map[string]interface{}{})
+	if len(snap) != 2 {
+		t.Errorf("snapshot should have inputs+vars: %#v", snap)
+	}
+}
+
+func TestBuildContextSnapshot_TrimsWhenOversized(t *testing.T) {
+	bigVars := make(map[string]interface{}, 30)
+	for i := 0; i < 30; i++ {
+		bigVars[string(rune('a'+i))+string(rune('a'+i))] = strings.Repeat("x", 200)
+	}
+	snap := BuildContextSnapshotWithOpts(
+		map[string]interface{}{"shape": "round"},
+		bigVars,
+		1024,
+		30,
+	)
+	encoded, err := json.Marshal(snap)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(encoded) > 1024 {
+		t.Errorf("snapshot exceeds 1024 bytes: %d", len(encoded))
+	}
+	if inputs, ok := snap["inputs"].(map[string]interface{}); !ok || inputs["shape"] != "round" {
+		t.Errorf("inputs not preserved: %#v", snap["inputs"])
+	}
+}
+
+// =============================================================================
+// Auto-enrichment defaults
+// =============================================================================
+
+func TestDefaultOrigin_PopulatesSdkConstants(t *testing.T) {
+	o := DefaultOrigin("step-x", "1.2.3")
+	if o.SDK != DefaultSDKName {
+		t.Errorf("SDK: %s want %s", o.SDK, DefaultSDKName)
+	}
+	if DefaultSDKName != "blok-go" {
+		t.Errorf("DefaultSDKName: %s want blok-go", DefaultSDKName)
+	}
+	if o.RuntimeKind != DefaultRuntimeKind {
+		t.Errorf("RuntimeKind: %s want %s", o.RuntimeKind, DefaultRuntimeKind)
+	}
+	if DefaultRuntimeKind != "runtime.go" {
+		t.Errorf("DefaultRuntimeKind: %s want runtime.go", DefaultRuntimeKind)
+	}
+	if o.Node != "step-x" {
+		t.Errorf("Node: %s", o.Node)
+	}
+	if o.SDKVersion != "1.2.3" {
+		t.Errorf("SDKVersion: %s", o.SDKVersion)
+	}
+}

package/dist/scaffold-repo/sdks/go/cmd/server/main.go

@@ -0,0 +1,45 @@
+// Package main provides the entry point for the blok Go runtime server.
+//
+// Usage:
+//
+//	go run ./cmd/server
+//
+// Environment variables:
+//
+//	PORT          - HTTP port (default: 8080)
+//	HOST          - Bind address (default: 0.0.0.0)
+//	VERSION       - Runtime version (default: 1.0.0)
+//	LOG_LEVEL     - Log level: DEBUG, INFO, WARN, ERROR (default: INFO)
+//	ENABLE_CORS   - Enable CORS: true/false (default: false)
+package main
+
+import (
+	"log"
+
+	blok "github.com/nickincloud/blok-go"
+	"github.com/nickincloud/blok-go/examples/nodes"
+)
+
+func main() {
+	// Create registry and register nodes
+	registry := blok.NewNodeRegistry()
+
+	// Register all example nodes
+	nodes.RegisterAll(registry)
+
+	// Register user nodes scaffolded under runtimes/go/nodes. This is a no-op
+	// in the SDK tree; blokctl regenerates register_user_nodes.go per project.
+	registerUserNodes(registry)
+
+	// Add middleware
+	logger := blok.NewLogger(blok.LogLevelInfo)
+	registry.Use(
+		blok.RecoveryMiddleware(),
+		blok.LoggingMiddleware(logger),
+	)
+
+	// Start serving (reads config from env, handles graceful shutdown)
+	if err := blok.ListenAndServe(registry); err != nil {
+		log.Fatalf("Server error: %v", err)
+	}
+}

package/dist/scaffold-repo/sdks/go/cmd/server/register_user_nodes.go

@@ -0,0 +1,12 @@
+// Code generated by blokctl. DO NOT EDIT.
+//
+// Default no-op shim. `blokctl dev` regenerates this in
+// .blok/runtimes/go/cmd/server with the user nodes scaffolded under
+// runtimes/go/nodes. Committed so the SDK compiles without codegen — e.g. the
+// cross-runtime CI build, which has no user nodes.
+package main
+
+import blok "github.com/nickincloud/blok-go"
+
+// registerUserNodes registers nodes scaffolded under runtimes/go/nodes.
+func registerUserNodes(registry *blok.NodeRegistry) {}

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

@@ -0,0 +1,157 @@
+package blok
+
+import (
+	"os"
+	"strconv"
+)
+
+// Transport identifies which server(s) to start.
+type Transport string
+
+const (
+	// TransportHTTP runs the HTTP server only (default; existing behavior).
+	TransportHTTP Transport = "http"
+	// TransportGRPC runs the gRPC server only.
+	TransportGRPC Transport = "grpc"
+	// TransportBoth runs HTTP and gRPC in the same process during migration.
+	TransportBoth Transport = "both"
+)
+
+// ServerConfig holds the configuration for the blok runtime server(s).
+type ServerConfig struct {
+	// Port is the HTTP port to listen on (default: 9001 — matches the
+	// runner's DEFAULT_PORTS.go).
+	Port int
+
+	// Host is the bind address (default: "0.0.0.0").
+	Host string
+
+	// Version is the runtime version reported in health checks.
+	Version string
+
+	// GRPCPort is the gRPC port to listen on (default: 10001 — matches the
+	// runner's DEFAULT_GRPC_PORTS.go = HTTP+1000).
+	GRPCPort int
+
+	// Transport selects which server(s) to start. Default: TransportHTTP.
+	// Override via the BLOK_TRANSPORT env var.
+	Transport Transport
+
+	// ReadTimeoutSec is the HTTP read timeout in seconds (default: 30).
+	ReadTimeoutSec int
+
+	// WriteTimeoutSec is the HTTP write timeout in seconds (default: 30).
+	WriteTimeoutSec int
+
+	// ShutdownTimeoutSec is the graceful shutdown timeout in seconds (default: 10).
+	ShutdownTimeoutSec int
+
+	// LogLevel is the minimum log level (default: INFO).
+	LogLevel LogLevel
+
+	// EnableCORS enables CORS headers on all responses (default: false).
+	EnableCORS bool
+}
+
+// DefaultConfig returns a ServerConfig with sensible defaults.
+func DefaultConfig() ServerConfig {
+	return ServerConfig{
+		Port:               9001,
+		Host:               "0.0.0.0",
+		Version:            "1.0.0",
+		GRPCPort:           10001,
+		Transport:          TransportHTTP,
+		ReadTimeoutSec:     30,
+		WriteTimeoutSec:    30,
+		ShutdownTimeoutSec: 10,
+		LogLevel:           LogLevelInfo,
+		EnableCORS:         false,
+	}
+}
+
+// LoadConfigFromEnv loads configuration from environment variables,
+// falling back to defaults for unset variables.
+//
+// Environment variables:
+//   - PORT: HTTP port (default: 9001 — matches DEFAULT_PORTS.go on the runner)
+//   - HOST: Bind address (default: 0.0.0.0)
+//   - VERSION: Runtime version (default: 1.0.0)
+//   - GRPC_PORT: gRPC port (default: 10001 — matches DEFAULT_GRPC_PORTS.go)
+//   - BLOK_TRANSPORT: "http" | "grpc" | "both" (default: "http")
+//   - READ_TIMEOUT: Read timeout in seconds (default: 30)
+//   - WRITE_TIMEOUT: Write timeout in seconds (default: 30)
+//   - SHUTDOWN_TIMEOUT: Shutdown timeout in seconds (default: 10)
+//   - LOG_LEVEL: Minimum log level: DEBUG, INFO, WARN, ERROR (default: INFO)
+//   - ENABLE_CORS: Enable CORS: true/false (default: false)
+func LoadConfigFromEnv() ServerConfig {
+	cfg := DefaultConfig()
+
+	if v := os.Getenv("PORT"); v != "" {
+		if port, err := strconv.Atoi(v); err == nil && port > 0 {
+			cfg.Port = port
+		}
+	}
+
+	if v := os.Getenv("HOST"); v != "" {
+		cfg.Host = v
+	}
+
+	if v := os.Getenv("VERSION"); v != "" {
+		cfg.Version = v
+	}
+
+	if v := os.Getenv("GRPC_PORT"); v != "" {
+		if port, err := strconv.Atoi(v); err == nil && port > 0 {
+			cfg.GRPCPort = port
+		}
+	}
+
+	if v := os.Getenv("BLOK_TRANSPORT"); v != "" {
+		switch Transport(v) {
+		case TransportHTTP, TransportGRPC, TransportBoth:
+			cfg.Transport = Transport(v)
+		}
+	}
+
+	if v := os.Getenv("READ_TIMEOUT"); v != "" {
+		if t, err := strconv.Atoi(v); err == nil && t > 0 {
+			cfg.ReadTimeoutSec = t
+		}
+	}
+
+	if v := os.Getenv("WRITE_TIMEOUT"); v != "" {
+		if t, err := strconv.Atoi(v); err == nil && t > 0 {
+			cfg.WriteTimeoutSec = t
+		}
+	}
+
+	if v := os.Getenv("SHUTDOWN_TIMEOUT"); v != "" {
+		if t, err := strconv.Atoi(v); err == nil && t > 0 {
+			cfg.ShutdownTimeoutSec = t
+		}
+	}
+
+	if v := os.Getenv("LOG_LEVEL"); v != "" {
+		switch v {
+		case "DEBUG":
+			cfg.LogLevel = LogLevelDebug
+		case "INFO":
+			cfg.LogLevel = LogLevelInfo
+		case "WARN":
+			cfg.LogLevel = LogLevelWarn
+		case "ERROR":
+			cfg.LogLevel = LogLevelError
+		}
+	}
+
+	if v := os.Getenv("ENABLE_CORS"); v == "true" || v == "1" {
+		cfg.EnableCORS = true
+	}
+
+	return cfg
+}
+
+// Address returns the host:port address string.
+func (c ServerConfig) Address() string {
+	return c.Host + ":" + strconv.Itoa(c.Port)
+}