blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Node/INodeHandler.cs

@@ -0,0 +1,17 @@
+using System.Text.Json;
+
+namespace Blok.Core.Node;
+
+/// <summary>
+/// INodeHandler is the core interface that all Blok nodes must implement.
+/// </summary>
+public interface INodeHandler
+{
+    /// <summary>
+    /// Execute the node logic with the given workflow context and node configuration.
+    /// </summary>
+    /// <param name="ctx">The workflow execution context.</param>
+    /// <param name="config">Node-specific configuration from the runner.</param>
+    /// <returns>A JSON element representing the result data.</returns>
+    Task<JsonElement> ExecuteAsync(Types.Context ctx, Dictionary<string, JsonElement> config);
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Node/NodeRegistry.cs

@@ -0,0 +1,128 @@
+using System.Collections.Concurrent;
+using System.Diagnostics;
+using System.Text.Json;
+using Blok.Core.Errors;
+using Blok.Core.Types;
+
+namespace Blok.Core.Node;
+
+/// <summary>
+/// NodeRegistry manages registered node handlers and dispatches execution requests.
+/// </summary>
+public class NodeRegistry
+{
+    private readonly ConcurrentDictionary<string, INodeHandler> _nodes = new();
+    private readonly string _version;
+
+    public NodeRegistry(string version = "1.0.0")
+    {
+        _version = version;
+    }
+
+    /// <summary>
+    /// Register a node handler under the given name.
+    /// </summary>
+    public void Register(string name, INodeHandler handler)
+    {
+        _nodes[name] = handler;
+    }
+
+    /// <summary>
+    /// Look up a node handler by name.
+    /// </summary>
+    public INodeHandler? Get(string name)
+    {
+        return _nodes.TryGetValue(name, out var handler) ? handler : null;
+    }
+
+    /// <summary>
+    /// Return the names of all registered nodes.
+    /// </summary>
+    public List<string> NodeNames()
+    {
+        return _nodes.Keys.ToList();
+    }
+
+    /// <summary>
+    /// Return the number of registered nodes.
+    /// </summary>
+    public int Count => _nodes.Count;
+
+    /// <summary>
+    /// Execute a node by dispatching through the registry.
+    /// </summary>
+    public async Task<ExecutionResult> ExecuteAsync(ExecutionRequest request)
+    {
+        var handler = Get(request.Node.Name);
+        if (handler is null)
+        {
+            return ExecutionResult.Fail($"node '{request.Node.Name}' not found in registry");
+        }
+
+        var memBefore = GC.GetTotalMemory(false);
+        var stopwatch = Stopwatch.StartNew();
+
+        try
+        {
+            var data = await handler.ExecuteAsync(request.Context, request.Node.Config);
+            stopwatch.Stop();
+            var memAfter = GC.GetTotalMemory(false);
+
+            var result = ExecutionResult.Ok(data).WithMetrics(new ExecutionMetrics
+            {
+                DurationMs = stopwatch.Elapsed.TotalMilliseconds,
+                MemoryBytes = Math.Max(0, memAfter - memBefore)
+            });
+
+            // Include context vars so the runner can propagate them downstream
+            if (request.Context.Vars is { Count: > 0 })
+            {
+                result.Vars = request.Context.Vars;
+            }
+
+            return result;
+        }
+        catch (BlokError be)
+        {
+            // 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.
+            stopwatch.Stop();
+            var result = new ExecutionResult
+            {
+                Success = false,
+                Data = null,
+                Errors = be,
+                Metrics = new ExecutionMetrics
+                {
+                    DurationMs = stopwatch.Elapsed.TotalMilliseconds,
+                },
+            };
+            return result;
+        }
+        catch (Exception ex)
+        {
+            stopwatch.Stop();
+            var result = ExecutionResult.Fail(ex.Message);
+            result.Metrics = new ExecutionMetrics
+            {
+                DurationMs = stopwatch.Elapsed.TotalMilliseconds
+            };
+            return result;
+        }
+    }
+
+    /// <summary>
+    /// Return the health status of the runtime.
+    /// </summary>
+    public HealthStatus GetHealth()
+    {
+        return new HealthStatus
+        {
+            Status = "healthy",
+            Version = _version,
+            NodesLoaded = NodeNames()
+        };
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Node/TypedNode.cs

@@ -0,0 +1,140 @@
+using System.ComponentModel.DataAnnotations;
+using System.Linq;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Blok.Core.Errors;
+using Blok.Core.Types;
+
+namespace Blok.Core.Node;
+
+/// <summary>
+/// Implemented by typed nodes (<see cref="TypedNode{TInput,TOutput}"/>) to expose
+/// a description + JSON Schema for the node catalog (GET /__blok/nodes) via gRPC
+/// ListNodes (SPEC-B P4). Legacy <see cref="INodeHandler"/> nodes don't implement it.
+/// </summary>
+public interface INodeReflector
+{
+    string Description { get; }
+    byte[] InputSchemaJson();
+    byte[] OutputSchemaJson();
+}
+
+/// <summary>
+/// Typed node base (SPEC-B P4) — the C# equivalent of the TypeScript
+/// <c>defineNode</c> / Python <c>@node</c> / Rust <c>TypedNode</c>. Declare typed
+/// <typeparamref name="TInput"/>/<typeparamref name="TOutput"/> (records with
+/// <see cref="System.ComponentModel.DataAnnotations"/> attributes) and override
+/// <see cref="RunAsync"/>; the SDK deserializes + validates the config into the
+/// typed input BEFORE running, serializes the output, and reflects both JSON
+/// Schemas — instead of a raw <c>Dictionary&lt;string, JsonElement&gt;</c>.
+/// </summary>
+/// <example>
+/// <code>
+/// public sealed record SearchInput([property: Required, MinLength(1)] string Query, int Limit = 10);
+/// public sealed record SearchOutput(IReadOnlyList&lt;string&gt; Results, int Count);
+///
+/// public sealed class SearchNode : TypedNode&lt;SearchInput, SearchOutput&gt;
+/// {
+///     public override string Name =&gt; "@acme/search";
+///     public override string Description =&gt; "Full-text search";
+///     public override Task&lt;SearchOutput&gt; RunAsync(Context ctx, SearchInput input)
+///     {
+///         var rows = DoSearch(input.Query, input.Limit);
+///         return Task.FromResult(new SearchOutput(rows, rows.Count));
+///     }
+/// }
+/// </code>
+/// </example>
+public abstract class TypedNode<TInput, TOutput> : INodeHandler, INodeReflector
+{
+    private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web);
+
+    /// <summary>The node's registered name (e.g. <c>"@acme/search"</c>).</summary>
+    public abstract string Name { get; }
+
+    /// <summary>Human-readable description, surfaced in the node catalog.</summary>
+    public virtual string Description => "";
+
+    /// <summary>Run the node with a VALIDATED, typed input.</summary>
+    public abstract Task<TOutput> RunAsync(Context ctx, TInput input);
+
+    /// <inheritdoc />
+    public async Task<JsonElement> ExecuteAsync(Context ctx, Dictionary<string, JsonElement> config)
+    {
+        TInput input;
+        try
+        {
+            var json = JsonSerializer.Serialize(config, Options);
+            input = JsonSerializer.Deserialize<TInput>(json, Options)
+                ?? throw new JsonException("config deserialized to null");
+        }
+        catch (Exception e) when (e is not BlokError)
+        {
+            throw ValidationError($"Input validation failed for node '{Name}': {e.Message}");
+        }
+
+        var results = new List<ValidationResult>();
+        if (!Validator.TryValidateObject(input!, new ValidationContext(input!), results, validateAllProperties: true))
+        {
+            var msg = string.Join("; ", results.Select(r => r.ErrorMessage ?? "invalid"));
+            throw ValidationError($"Input validation failed for node '{Name}': {msg}");
+        }
+
+        var output = await RunAsync(ctx, input);
+        return JsonSerializer.SerializeToElement(output, Options);
+    }
+
+    private BlokError ValidationError(string message) =>
+        BlokError.Validation().Code("NODE_INPUT_VALIDATION").Message(message).HttpStatus(400).Node(Name).Build();
+
+    /// <inheritdoc />
+    public byte[] InputSchemaJson() => SchemaBytes(typeof(TInput));
+
+    /// <inheritdoc />
+    public byte[] OutputSchemaJson() => SchemaBytes(typeof(TOutput));
+
+    private static byte[] SchemaBytes(Type type)
+    {
+        try
+        {
+            // NJsonSchema reflects PascalCase property names, but the runtime
+            // serializes with Web (camelCase) options — re-key the schema with
+            // the SAME naming policy so the catalog schema matches the wire.
+            var root = JsonNode.Parse(NJsonSchema.JsonSchema.FromType(type).ToJson())!.AsObject();
+            CamelCaseProperties(root);
+            return Encoding.UTF8.GetBytes(root.ToJsonString());
+        }
+        catch
+        {
+            return Array.Empty<byte>();
+        }
+    }
+
+    private static string Camel(string name) => JsonNamingPolicy.CamelCase.ConvertName(name);
+
+    private static void CamelCaseProperties(JsonObject schema)
+    {
+        if (schema["properties"] is JsonObject props)
+        {
+            var rebuilt = new JsonObject();
+            foreach (var key in props.Select(p => p.Key).ToList())
+            {
+                var child = props[key];
+                props.Remove(key); // detach so the node can be re-parented
+                if (child is JsonObject childObj) CamelCaseProperties(childObj);
+                rebuilt[Camel(key)] = child;
+            }
+            schema["properties"] = rebuilt;
+        }
+        if (schema["required"] is JsonArray required)
+        {
+            var rebuilt = new JsonArray();
+            foreach (var item in required.Select(x => x!.GetValue<string>()).ToList())
+            {
+                rebuilt.Add(Camel(item));
+            }
+            schema["required"] = rebuilt;
+        }
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Nodes/ApiCallNode.cs

@@ -0,0 +1,129 @@
+using System.Text;
+using System.Text.Json;
+using Blok.Core.Errors;
+using Blok.Core.Node;
+
+namespace Blok.Core.Nodes;
+
+/// <summary>
+/// ApiCallNode makes HTTP requests to external APIs.
+///
+/// Config:
+///   - url (string, required): The URL to call
+///   - method (string, optional): HTTP method (default: GET)
+///   - timeout (number, optional): Timeout in seconds (default: 10)
+/// </summary>
+public class ApiCallNode : INodeHandler
+{
+    public async Task<JsonElement> ExecuteAsync(Types.Context ctx, Dictionary<string, JsonElement> config)
+    {
+        // Get URL (required)
+        if (!config.TryGetValue("url", out var urlProp) || urlProp.ValueKind != JsonValueKind.String)
+        {
+            throw NodeException.Configuration("'url' is required in node config");
+        }
+        var url = urlProp.GetString()!;
+
+        // Get method (optional, default GET)
+        var method = "GET";
+        if (config.TryGetValue("method", out var methodProp) && methodProp.ValueKind == JsonValueKind.String)
+        {
+            method = methodProp.GetString()?.ToUpperInvariant() ?? "GET";
+        }
+
+        // Get timeout (optional, default 10)
+        var timeoutSeconds = 10;
+        if (config.TryGetValue("timeout", out var timeoutProp) && timeoutProp.ValueKind == JsonValueKind.Number)
+        {
+            timeoutSeconds = timeoutProp.TryGetInt32(out var t) ? t : 10;
+        }
+
+        using var httpClient = new HttpClient
+        {
+            Timeout = TimeSpan.FromSeconds(timeoutSeconds)
+        };
+
+        try
+        {
+            var httpMethod = method switch
+            {
+                "POST" => HttpMethod.Post,
+                "PUT" => HttpMethod.Put,
+                "PATCH" => HttpMethod.Patch,
+                "DELETE" => HttpMethod.Delete,
+                "HEAD" => HttpMethod.Head,
+                _ => HttpMethod.Get
+            };
+
+            var requestMessage = new HttpRequestMessage(httpMethod, url);
+
+            // Add body for POST/PUT/PATCH
+            if (method is "POST" or "PUT" or "PATCH")
+            {
+                if (ctx.Request.Body.ValueKind == JsonValueKind.Object &&
+                    ctx.Request.Body.TryGetProperty("body", out var bodyProp))
+                {
+                    requestMessage.Content = new StringContent(
+                        bodyProp.GetRawText(),
+                        Encoding.UTF8,
+                        "application/json");
+                }
+            }
+
+            // Add headers from config
+            if (config.TryGetValue("headers", out var headersProp) && headersProp.ValueKind == JsonValueKind.Object)
+            {
+                foreach (var header in headersProp.EnumerateObject())
+                {
+                    if (header.Value.ValueKind == JsonValueKind.String)
+                    {
+                        requestMessage.Headers.TryAddWithoutValidation(header.Name, header.Value.GetString());
+                    }
+                }
+            }
+
+            var response = await httpClient.SendAsync(requestMessage);
+            var statusCode = (int)response.StatusCode;
+            var bodyText = await response.Content.ReadAsStringAsync();
+
+            // Try to parse response as JSON, fall back to string
+            JsonElement data;
+            try
+            {
+                data = JsonDocument.Parse(bodyText).RootElement.Clone();
+            }
+            catch
+            {
+                data = JsonDocument.Parse($"\"{bodyText.Replace("\"", "\\\"")}\"").RootElement.Clone();
+            }
+
+            // Collect response headers
+            var responseHeaders = new Dictionary<string, string>();
+            foreach (var header in response.Headers)
+            {
+                responseHeaders[header.Key] = string.Join(", ", header.Value);
+            }
+            foreach (var header in response.Content.Headers)
+            {
+                responseHeaders[header.Key] = string.Join(", ", header.Value);
+            }
+
+            var result = JsonSerializer.Serialize(new
+            {
+                status = statusCode,
+                data,
+                headers = responseHeaders
+            });
+
+            return JsonDocument.Parse(result).RootElement.Clone();
+        }
+        catch (TaskCanceledException)
+        {
+            throw NodeException.Network($"request to {url} timed out after {timeoutSeconds}s");
+        }
+        catch (HttpRequestException ex)
+        {
+            throw NodeException.Network($"request to {url} failed: {ex.Message}");
+        }
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Nodes/BlokErrorDemoNode.cs

@@ -0,0 +1,125 @@
+using System.Text.Json;
+using Blok.Core.Errors;
+using Blok.Core.Node;
+
+namespace Blok.Core.Nodes;
+
+/// <summary>
+/// Example node demonstrating the structured <see cref="BlokError"/> API per
+/// master plan §17.
+///
+/// <para>Used by the cross-language E2E test
+/// (<c>core/runner/__tests__/integration/runtimes/csharp-grpc.integration.test.ts</c>)
+/// to verify that a C#-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).</para>
+///
+/// <para>Triggered via the <c>mode</c> config:</para>
+/// <list type="bullet">
+///   <item><c>mode="dependency"</c> (default) — throws <c>BlokError.Dependency()</c>
+///     with a cause chain rooted in an <see cref="IOException"/>.</item>
+///   <item><c>mode="rate-limit"</c> — throws <c>BlokError.RateLimit()</c>
+///     with <c>retry_after_ms</c>.</item>
+///   <item><c>mode="validation"</c> — throws <c>BlokError.Validation()</c>
+///     with <c>details.issues</c>.</item>
+///   <item><c>mode="ok"</c> — returns success.</item>
+/// </list>
+/// </summary>
+public class BlokErrorDemoNode : INodeHandler
+{
+    public Task<JsonElement> ExecuteAsync(Types.Context ctx, Dictionary<string, JsonElement> config)
+    {
+        var mode = "dependency";
+        if (config.TryGetValue("mode", out var modeVal) && modeVal.ValueKind == JsonValueKind.String)
+        {
+            mode = modeVal.GetString() ?? "dependency";
+        }
+
+        if (mode == "ok")
+        {
+            var okJson = JsonSerializer.Serialize(new { ok = true, language = "csharp" });
+            return Task.FromResult(JsonDocument.Parse(okJson).RootElement.Clone());
+        }
+
+        // Build the snapshot from the resolved inputs + ctx.vars.
+        var configMap = ConfigToObjectMap(config);
+        var snapshot = BuildContextSnapshot.Of(configMap, ctx.Vars ?? new Dictionary<string, object?>());
+
+        if (mode == "rate-limit")
+        {
+            throw BlokError.RateLimit()
+                .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.")
+                .RetryAfterMs(60_000)
+                .DocUrl("https://docs.example.com/errors/rate-limit")
+                .Details(new Dictionary<string, object?>
+                {
+                    ["limit"] = 5000,
+                    ["remaining"] = 0,
+                })
+                .ContextSnapshot(snapshot)
+                .Build();
+        }
+
+        if (mode == "validation")
+        {
+            throw 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(new Dictionary<string, object?>
+                {
+                    ["issues"] = new List<Dictionary<string, object?>>
+                    {
+                        new() { ["path"] = new List<string> { "email" }, ["message"] = "Required" },
+                        new() { ["path"] = new List<string> { "name" }, ["message"] = "Required" },
+                    },
+                })
+                .ContextSnapshot(snapshot)
+                .Build();
+        }
+
+        // default: dependency with a cause chain rooted in an IOException.
+        var cause = new IOException("[Errno 61] Connection refused");
+        throw 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)
+            .RetryAfter(TimeSpan.FromSeconds(5))
+            .DocUrl("https://docs.example.com/errors/POSTGRES_CONNECT_TIMEOUT")
+            .Details(new Dictionary<string, object?>
+            {
+                ["host"] = "db.internal",
+                ["port"] = 5432,
+                ["timeout_ms"] = 5000,
+            })
+            .ContextSnapshot(snapshot)
+            .Build();
+    }
+
+    private static Dictionary<string, object?> ConfigToObjectMap(Dictionary<string, JsonElement> config)
+    {
+        var map = new Dictionary<string, object?>();
+        foreach (var kv in config)
+        {
+            map[kv.Key] = JsonElementToObject(kv.Value);
+        }
+        return map;
+    }
+
+    private static object? JsonElementToObject(JsonElement el) => el.ValueKind switch
+    {
+        JsonValueKind.String => el.GetString(),
+        JsonValueKind.Number => el.TryGetInt64(out var l) ? (object)l : el.GetDouble(),
+        JsonValueKind.True => true,
+        JsonValueKind.False => false,
+        JsonValueKind.Null => null,
+        _ => el.GetRawText(),
+    };
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Nodes/ChainTestNode.cs

@@ -0,0 +1,79 @@
+using System.Text.Json;
+using Blok.Core.Node;
+using Blok.Core.Types;
+
+namespace Blok.Core.Nodes;
+
+/// <summary>
+/// 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.
+/// </summary>
+public class ChainTestNode : INodeHandler
+{
+    public async Task<JsonElement> ExecuteAsync(Context ctx, Dictionary<string, JsonElement> config)
+    {
+        await Task.CompletedTask;
+
+        // 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.
+        var chain = new List<object>();
+        JsonElement chainSrc = default;
+        if (config.TryGetValue("chain", out var configChain) && configChain.ValueKind == JsonValueKind.Array)
+        {
+            chainSrc = configChain;
+        }
+        else if (ctx.Request?.Body.ValueKind == JsonValueKind.Object &&
+                 ctx.Request.Body.TryGetProperty("chain", out var bodyChain) &&
+                 bodyChain.ValueKind == JsonValueKind.Array)
+        {
+            chainSrc = bodyChain;
+        }
+        if (chainSrc.ValueKind == JsonValueKind.Array)
+        {
+            foreach (var item in chainSrc.EnumerateArray())
+            {
+                chain.Add(item);
+            }
+        }
+
+        // Read origin — same dual-read.
+        var origin = "unknown";
+        if (config.TryGetValue("origin", out var configOrigin) &&
+            configOrigin.ValueKind == JsonValueKind.String &&
+            !string.IsNullOrEmpty(configOrigin.GetString()))
+        {
+            origin = configOrigin.GetString() ?? "unknown";
+        }
+        else if (ctx.Request?.Body.ValueKind == JsonValueKind.Object &&
+                 ctx.Request.Body.TryGetProperty("origin", out var originProp) &&
+                 originProp.ValueKind == JsonValueKind.String)
+        {
+            origin = originProp.GetString() ?? "unknown";
+        }
+
+        // Append this language's entry
+        var entry = new
+        {
+            language = "csharp",
+            order = chain.Count + 1,
+            timestamp = DateTime.UtcNow.ToString("o")
+        };
+        chain.Add(entry);
+
+        // Store in context vars
+        ctx.Vars["chain"] = JsonSerializer.SerializeToElement(chain);
+
+        // Return updated chain
+        var result = new
+        {
+            chain,
+            origin
+        };
+
+        return JsonSerializer.SerializeToElement(result);
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Nodes/HelloWorldNode.cs

@@ -0,0 +1,45 @@
+using System.Text.Json;
+using Blok.Core.Node;
+
+namespace Blok.Core.Nodes;
+
+/// <summary>
+/// HelloWorldNode greets the user with a configurable prefix.
+/// </summary>
+public class HelloWorldNode : INodeHandler
+{
+    public Task<JsonElement> ExecuteAsync(Types.Context ctx, Dictionary<string, JsonElement> config)
+    {
+        // Get name from body, default to "World"
+        var name = "World";
+        if (ctx.Request.Body.ValueKind == JsonValueKind.Object &&
+            ctx.Request.Body.TryGetProperty("name", out var nameProp) &&
+            nameProp.ValueKind == JsonValueKind.String)
+        {
+            name = nameProp.GetString() ?? "World";
+        }
+
+        // Get prefix from config, default to "Hello"
+        var prefix = "Hello";
+        if (config.TryGetValue("prefix", out var prefixProp) &&
+            prefixProp.ValueKind == JsonValueKind.String)
+        {
+            prefix = prefixProp.GetString() ?? "Hello";
+        }
+
+        var message = $"{prefix}, {name}!";
+
+        // Store greeting in context vars
+        ctx.SetVar("greeting", message);
+
+        var result = JsonSerializer.Serialize(new
+        {
+            message,
+            timestamp = DateTime.UtcNow.ToString("O"),
+            language = "csharp"
+        });
+
+        var element = JsonDocument.Parse(result).RootElement.Clone();
+        return Task.FromResult(element);
+    }
+}