blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/middleware/Middleware.java

@@ -0,0 +1,29 @@
+package com.blok.blok.middleware;
+
+import com.blok.blok.node.NodeHandler;
+
+/**
+ * Functional interface for middleware that wraps node handler execution.
+ * Middleware can add cross-cutting behavior such as logging, recovery, or validation.
+ * <p>
+ * Example:
+ * <pre>{@code
+ * Middleware timing = next -> (ctx, config) -> {
+ *     long start = System.nanoTime();
+ *     Object result = next.execute(ctx, config);
+ *     System.out.println("Took " + (System.nanoTime() - start) / 1_000_000 + "ms");
+ *     return result;
+ * };
+ * }</pre>
+ */
+@FunctionalInterface
+public interface Middleware {
+
+    /**
+     * Wraps the given handler with additional behavior.
+     *
+     * @param next the next handler in the chain
+     * @return a wrapped handler
+     */
+    NodeHandler wrap(NodeHandler next);
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/middleware/MiddlewareChain.java

@@ -0,0 +1,59 @@
+package com.blok.blok.middleware;
+
+import com.blok.blok.node.NodeHandler;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Composes multiple middleware into a single middleware.
+ * Middleware is applied in order: first middleware is outermost.
+ */
+public class MiddlewareChain implements Middleware {
+
+    private final List<Middleware> middlewares;
+
+    /**
+     * Creates a chain from the given middlewares.
+     *
+     * @param middlewares the middlewares to chain
+     */
+    public MiddlewareChain(Middleware... middlewares) {
+        this.middlewares = new ArrayList<>();
+        if (middlewares != null) {
+            this.middlewares.addAll(Arrays.asList(middlewares));
+        }
+    }
+
+    /**
+     * Creates a chain from a list of middlewares.
+     *
+     * @param middlewares the middlewares to chain
+     */
+    public MiddlewareChain(List<Middleware> middlewares) {
+        this.middlewares = middlewares != null ? new ArrayList<>(middlewares) : new ArrayList<>();
+    }
+
+    /**
+     * Adds a middleware to the end of the chain.
+     *
+     * @param middleware the middleware to add
+     * @return this chain for fluent use
+     */
+    public MiddlewareChain add(Middleware middleware) {
+        if (middleware != null) {
+            middlewares.add(middleware);
+        }
+        return this;
+    }
+
+    @Override
+    public NodeHandler wrap(NodeHandler handler) {
+        NodeHandler current = handler;
+        for (int i = middlewares.size() - 1; i >= 0; i--) {
+            current = middlewares.get(i).wrap(current);
+        }
+        return current;
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/middleware/RecoveryMiddleware.java

@@ -0,0 +1,53 @@
+package com.blok.blok.middleware;
+
+import com.blok.blok.errors.BlokError;
+import com.blok.blok.errors.ErrorCategory;
+import com.blok.blok.errors.NodeException;
+import com.blok.blok.node.NodeHandler;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Middleware that catches all exceptions during node execution
+ * and converts them to structured NodeExceptions.
+ * <p>
+ * Structured exceptions ({@link BlokError}, {@link NodeException}) are
+ * re-thrown as-is so the registry / gRPC servicer can serialize them
+ * losslessly. All other exceptions are wrapped in an EXECUTION
+ * NodeException with the stack trace captured in the details.
+ */
+public class RecoveryMiddleware implements Middleware {
+
+    @Override
+    public NodeHandler wrap(NodeHandler next) {
+        return (ctx, config) -> {
+            try {
+                return next.execute(ctx, config);
+            } catch (BlokError e) {
+                // Master plan §17 BlokError passes through verbatim — the
+                // registry catches it directly and stashes the typed instance
+                // on `ExecutionResult.errors` for the gRPC servicer.
+                throw e;
+            } catch (NodeException e) {
+                // Legacy structured exceptions pass through as-is too.
+                throw e;
+            } catch (Exception e) {
+                // Capture stack trace
+                StringWriter sw = new StringWriter();
+                e.printStackTrace(new PrintWriter(sw));
+
+                Map<String, Object> details = new HashMap<>();
+                details.put("stack", sw.toString());
+
+                String message = e.getMessage() != null
+                        ? "recovered: " + e.getMessage()
+                        : "recovered: " + e.getClass().getSimpleName();
+
+                throw new NodeException(message, 500, ErrorCategory.EXECUTION, details, e);
+            }
+        };
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/node/NodeHandler.java

@@ -0,0 +1,40 @@
+package com.blok.blok.node;
+
+import com.blok.blok.types.Context;
+
+import java.util.Map;
+
+/**
+ * Interface that all Blok workflow nodes must implement.
+ * <p>
+ * Nodes receive the workflow context and node-specific configuration,
+ * execute their logic, and return data or throw an exception.
+ * <p>
+ * Example:
+ * <pre>{@code
+ * public class MyNode implements NodeHandler {
+ *     @Override
+ *     public Object execute(Context ctx, Map<String, Object> config) throws Exception {
+ *         String name = "World";
+ *         Map<String, Object> body = ctx.getRequest().bodyMap();
+ *         if (body != null && body.get("name") instanceof String s) {
+ *             name = s;
+ *         }
+ *         return Map.of("message", "Hello, " + name + "!");
+ *     }
+ * }
+ * }</pre>
+ */
+@FunctionalInterface
+public interface NodeHandler {
+
+    /**
+     * Executes the node logic.
+     *
+     * @param ctx    the workflow execution context
+     * @param config the node-specific configuration map
+     * @return the execution result data (any serializable object)
+     * @throws Exception if the execution fails
+     */
+    Object execute(Context ctx, Map<String, Object> config) throws Exception;
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/node/NodeReflector.java

@@ -0,0 +1,18 @@
+package com.blok.blok.node;
+
+/**
+ * Implemented by typed nodes ({@link TypedNode}) to expose a description + JSON
+ * Schema for the node catalog (GET /__blok/nodes) via gRPC ListNodes
+ * (SPEC-B P4). Legacy {@link NodeHandler} nodes do not implement it.
+ */
+public interface NodeReflector {
+
+    /** Human-readable description, surfaced in the node catalog. */
+    String description();
+
+    /** JSON Schema for the input, or {@code null}. */
+    String inputSchemaJson();
+
+    /** JSON Schema for the output, or {@code null}. */
+    String outputSchemaJson();
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/node/NodeRegistry.java

@@ -0,0 +1,205 @@
+package com.blok.blok.node;
+
+import com.blok.blok.errors.BlokError;
+import com.blok.blok.errors.NodeException;
+import com.blok.blok.middleware.Middleware;
+import com.blok.blok.types.*;
+
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Manages registered node handlers and executes them.
+ * Thread-safe: uses ConcurrentHashMap for node storage.
+ */
+public class NodeRegistry {
+
+    private final ConcurrentHashMap<String, NodeHandler> nodes = new ConcurrentHashMap<>();
+    private final List<Middleware> middlewares = Collections.synchronizedList(new ArrayList<>());
+
+    /**
+     * Registers a node handler with the given name.
+     *
+     * @param name    the node name
+     * @param handler the node handler implementation
+     * @throws IllegalArgumentException if name or handler is null
+     */
+    public void register(String name, NodeHandler handler) {
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("node name must not be null or blank");
+        }
+        if (handler == null) {
+            throw new IllegalArgumentException("handler must not be null");
+        }
+        nodes.put(name, handler);
+    }
+
+    /**
+     * Adds middleware to be applied to all node executions.
+     *
+     * @param middleware the middleware to add
+     */
+    public void use(Middleware middleware) {
+        if (middleware == null) {
+            throw new IllegalArgumentException("middleware must not be null");
+        }
+        middlewares.add(middleware);
+    }
+
+    /**
+     * Retrieves a node handler by name.
+     *
+     * @param name the node name
+     * @return the handler, or null if not found
+     */
+    public NodeHandler get(String name) {
+        if (name == null) {
+            return null;
+        }
+        return nodes.get(name);
+    }
+
+    /**
+     * Returns the names of all registered nodes.
+     *
+     * @return a list of node names
+     */
+    public List<String> nodeNames() {
+        return new ArrayList<>(nodes.keySet());
+    }
+
+    /**
+     * Executes a node by processing an ExecutionRequest.
+     * Applies all registered middleware and captures timing/memory metrics.
+     *
+     * @param request the execution request
+     * @return the execution result (never null)
+     */
+    public ExecutionResult execute(ExecutionRequest request) {
+        if (request == null) {
+            return ExecutionResult.error("execution request must not be null");
+        }
+
+        long startNanos = System.nanoTime();
+        Runtime runtime = Runtime.getRuntime();
+        long memBefore = runtime.totalMemory() - runtime.freeMemory();
+
+        // Look up handler
+        NodeConfig nodeConfig = request.getNode();
+        if (nodeConfig == null || nodeConfig.getName() == null) {
+            return ExecutionResult.error("node configuration is missing");
+        }
+
+        String nodeName = nodeConfig.getName();
+        NodeHandler handler = get(nodeName);
+        if (handler == null) {
+            return ExecutionResult.error("node '" + nodeName + "' not found");
+        }
+
+        // Apply middleware chain (outermost first)
+        NodeHandler wrapped = handler;
+        List<Middleware> mws;
+        synchronized (middlewares) {
+            mws = new ArrayList<>(middlewares);
+        }
+        for (int i = mws.size() - 1; i >= 0; i--) {
+            wrapped = mws.get(i).wrap(wrapped);
+        }
+
+        // Execute
+        Context ctx = request.getContext();
+        if (ctx == null) {
+            ctx = new Context();
+        }
+        Map<String, Object> config = (nodeConfig.getConfig() != null)
+                ? nodeConfig.getConfig()
+                : new HashMap<>();
+
+        try {
+            Object data = wrapped.execute(ctx, config);
+
+            // Calculate metrics
+            long durationNanos = System.nanoTime() - startNanos;
+            double durationMs = durationNanos / 1_000_000.0;
+            long memAfter = runtime.totalMemory() - runtime.freeMemory();
+            long memUsed = Math.max(0, memAfter - memBefore);
+
+            ExecutionMetrics metrics = new ExecutionMetrics(durationMs, null, memUsed);
+            ExecutionResult result = ExecutionResult.success(data).withMetrics(metrics);
+
+            // Include context vars so the runner can propagate them downstream
+            if (ctx.getVars() != null && !ctx.getVars().isEmpty()) {
+                result.setVars(ctx.getVars());
+            }
+
+            return result;
+
+        } catch (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.
+            long durationNanos = System.nanoTime() - startNanos;
+            double durationMs = durationNanos / 1_000_000.0;
+            long memAfter = runtime.totalMemory() - runtime.freeMemory();
+            long memUsed = Math.max(0, memAfter - memBefore);
+
+            ExecutionMetrics metrics = new ExecutionMetrics(durationMs, null, memUsed);
+
+            ExecutionResult result = new ExecutionResult();
+            result.setSuccess(false);
+            result.setErrors(e);
+            result.setMetrics(metrics);
+            return result;
+
+        } catch (NodeException e) {
+            long durationNanos = System.nanoTime() - startNanos;
+            double durationMs = durationNanos / 1_000_000.0;
+            long memAfter = runtime.totalMemory() - runtime.freeMemory();
+            long memUsed = Math.max(0, memAfter - memBefore);
+
+            ExecutionMetrics metrics = new ExecutionMetrics(durationMs, null, memUsed);
+
+            Map<String, Object> errorMap = new HashMap<>();
+            errorMap.put("message", e.getMessage());
+            errorMap.put("code", e.getCode());
+            errorMap.put("category", e.getCategory().name());
+            if (e.getDetails() != null && !e.getDetails().isEmpty()) {
+                errorMap.put("details", e.getDetails());
+            }
+
+            ExecutionResult result = new ExecutionResult();
+            result.setSuccess(false);
+            result.setErrors(errorMap);
+            result.setMetrics(metrics);
+            return result;
+
+        } catch (Exception e) {
+            long durationNanos = System.nanoTime() - startNanos;
+            double durationMs = durationNanos / 1_000_000.0;
+            long memAfter = runtime.totalMemory() - runtime.freeMemory();
+            long memUsed = Math.max(0, memAfter - memBefore);
+
+            ExecutionMetrics metrics = new ExecutionMetrics(durationMs, null, memUsed);
+
+            Map<String, String> errorMap = new HashMap<>();
+            errorMap.put("message", e.getMessage() != null ? e.getMessage() : "unknown error");
+
+            ExecutionResult result = new ExecutionResult();
+            result.setSuccess(false);
+            result.setErrors(errorMap);
+            result.setMetrics(metrics);
+            return result;
+        }
+    }
+
+    /**
+     * Returns the health status of the registry.
+     *
+     * @param version the runtime version string
+     * @return health status
+     */
+    public HealthStatus health(String version) {
+        return new HealthStatus("healthy", version, nodeNames());
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/node/TypedNode.java

@@ -0,0 +1,143 @@
+package com.blok.blok.node;
+
+import com.blok.blok.errors.BlokError;
+import com.blok.blok.types.Context;
+import com.google.gson.Gson;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Typed node base (SPEC-B P4) — the Java equivalent of the TypeScript
+ * {@code defineNode} / Python {@code @node} / Rust {@code TypedNode} / Go
+ * {@code DefineNode}. Declare typed {@code I}/{@code O} types (e.g. records) and
+ * implement {@link #run}; the SDK converts the raw config into the typed input
+ * BEFORE running (a type mismatch → structured {@link BlokError}, HTTP 400),
+ * and reflects both JSON Schemas for the catalog — instead of a raw
+ * {@code Map<String, Object>}.
+ *
+ * <p>Register like any handler:
+ * {@code registry.register("@acme/search", new SearchNode());}
+ *
+ * <pre>{@code
+ * public record SearchInput(String query, int limit) {}
+ * public record SearchOutput(List<String> results, int count) {}
+ *
+ * public final class SearchNode extends TypedNode<SearchInput, SearchOutput> {
+ *     public String name() { return "@acme/search"; }
+ *     public String description() { return "Full-text search"; }
+ *     protected Class<SearchInput> inputClass() { return SearchInput.class; }
+ *     protected Class<?> outputClass() { return SearchOutput.class; }
+ *     protected SearchOutput run(Context ctx, SearchInput input) {
+ *         var rows = Collections.nCopies(input.limit(), input.query());
+ *         return new SearchOutput(rows, rows.size());
+ *     }
+ * }
+ * }</pre>
+ *
+ * @param <I> the typed input
+ * @param <O> the typed output
+ */
+public abstract class TypedNode<I, O> implements NodeHandler, NodeReflector {
+
+    private static final Gson GSON = new Gson();
+
+    /** The node's registered name (e.g. {@code "@acme/search"}). */
+    public abstract String name();
+
+    /** {@inheritDoc} Human-readable description; override to set. */
+    @Override
+    public String description() {
+        return "";
+    }
+
+    /** The class of the typed input (e.g. {@code SearchInput.class}). */
+    protected abstract Class<I> inputClass();
+
+    /** The class of the typed output, for schema reflection; {@code null} to skip. */
+    protected Class<?> outputClass() {
+        return null;
+    }
+
+    /** Run the node with a VALIDATED, typed input. */
+    protected abstract O run(Context ctx, I input) throws Exception;
+
+    @Override
+    public Object execute(Context ctx, Map<String, Object> config) throws Exception {
+        I input;
+        try {
+            input = GSON.fromJson(GSON.toJsonTree(config), inputClass());
+        } catch (RuntimeException e) {
+            throw BlokError.validation()
+                    .code("NODE_INPUT_VALIDATION")
+                    .message("Input validation failed for node '" + name() + "': " + e.getMessage())
+                    .httpStatus(400)
+                    .node(name())
+                    .build();
+        }
+        return run(ctx, input);
+    }
+
+    @Override
+    public String inputSchemaJson() {
+        return reflectSchema(inputClass());
+    }
+
+    @Override
+    public String outputSchemaJson() {
+        Class<?> out = outputClass();
+        return out == null ? null : reflectSchema(out);
+    }
+
+    /** Build a minimal JSON Schema from the type's declared instance fields. */
+    private static String reflectSchema(Class<?> type) {
+        try {
+            JsonObject schema = new JsonObject();
+            schema.addProperty("type", "object");
+            JsonObject properties = new JsonObject();
+            JsonArray required = new JsonArray();
+            for (Field field : type.getDeclaredFields()) {
+                if (Modifier.isStatic(field.getModifiers())) {
+                    continue;
+                }
+                JsonObject property = new JsonObject();
+                property.addProperty("type", jsonType(field.getType()));
+                properties.add(field.getName(), property);
+                if (field.getType().isPrimitive()) {
+                    required.add(field.getName());
+                }
+            }
+            schema.add("properties", properties);
+            if (required.size() > 0) {
+                schema.add("required", required);
+            }
+            return GSON.toJson(schema);
+        } catch (RuntimeException e) {
+            return null;
+        }
+    }
+
+    private static String jsonType(Class<?> type) {
+        if (type == int.class || type == Integer.class || type == long.class || type == Long.class
+                || type == short.class || type == Short.class) {
+            return "integer";
+        }
+        if (type == double.class || type == Double.class || type == float.class || type == Float.class) {
+            return "number";
+        }
+        if (type == boolean.class || type == Boolean.class) {
+            return "boolean";
+        }
+        if (type == String.class) {
+            return "string";
+        }
+        if (type.isArray() || List.class.isAssignableFrom(type)) {
+            return "array";
+        }
+        return "object";
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/nodes/ApiCallNode.java

@@ -0,0 +1,145 @@
+package com.blok.blok.nodes;
+
+import com.blok.blok.errors.NodeException;
+import com.blok.blok.node.NodeHandler;
+import com.blok.blok.types.Context;
+import com.google.gson.Gson;
+import com.google.gson.JsonSyntaxException;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Node that makes HTTP requests to external APIs.
+ * <p>
+ * Config:
+ * <ul>
+ *   <li>url (string, required) - The URL to call</li>
+ *   <li>method (string, optional) - HTTP method (default: "GET")</li>
+ *   <li>timeout (number, optional) - Timeout in seconds (default: 10)</li>
+ *   <li>headers (map, optional) - Additional request headers</li>
+ * </ul>
+ * Input (request body):
+ * <ul>
+ *   <li>body (any, optional) - Request body for POST/PUT/PATCH</li>
+ * </ul>
+ * Output:
+ * <ul>
+ *   <li>status (number) - HTTP status code</li>
+ *   <li>data (any) - Parsed response body</li>
+ *   <li>headers (map) - Response headers</li>
+ * </ul>
+ */
+public class ApiCallNode implements NodeHandler {
+
+    private static final Gson GSON = new Gson();
+
+    @Override
+    public Object execute(Context ctx, Map<String, Object> config) throws Exception {
+        if (config == null) {
+            throw NodeException.configuration("config is required for api-call node");
+        }
+
+        // Get URL from config (required)
+        Object urlVal = config.get("url");
+        if (!(urlVal instanceof String url) || url.isEmpty()) {
+            throw NodeException.configuration("'url' is required in node config");
+        }
+
+        // Get method from config, default to GET
+        String method = "GET";
+        Object methodVal = config.get("method");
+        if (methodVal instanceof String m && !m.isEmpty()) {
+            method = m.toUpperCase();
+        }
+
+        // Get timeout from config, default to 10 seconds
+        int timeout = 10;
+        Object timeoutVal = config.get("timeout");
+        if (timeoutVal instanceof Number n && n.intValue() > 0) {
+            timeout = n.intValue();
+        }
+
+        // Build the HTTP request
+        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
+                .uri(URI.create(url))
+                .timeout(Duration.ofSeconds(timeout));
+
+        // Set custom headers from config
+        Object headersVal = config.get("headers");
+        if (headersVal instanceof Map<?, ?> headersMap) {
+            for (Map.Entry<?, ?> entry : headersMap.entrySet()) {
+                if (entry.getKey() instanceof String key && entry.getValue() instanceof String value) {
+                    requestBuilder.header(key, value);
+                }
+            }
+        }
+
+        // Prepare request body
+        String requestBody = null;
+        Map<String, Object> body = ctx.getRequest().bodyMap();
+        if (body != null && body.containsKey("body") && body.get("body") != null) {
+            requestBody = GSON.toJson(body.get("body"));
+        }
+
+        // Set method and body
+        switch (method) {
+            case "POST" -> {
+                requestBuilder.header("Content-Type", "application/json");
+                requestBuilder.POST(HttpRequest.BodyPublishers.ofString(
+                        requestBody != null ? requestBody : ""));
+            }
+            case "PUT" -> {
+                requestBuilder.header("Content-Type", "application/json");
+                requestBuilder.PUT(HttpRequest.BodyPublishers.ofString(
+                        requestBody != null ? requestBody : ""));
+            }
+            case "DELETE" -> requestBuilder.DELETE();
+            default -> requestBuilder.GET();
+        }
+
+        // Execute the request
+        try {
+            HttpClient client = HttpClient.newBuilder()
+                    .connectTimeout(Duration.ofSeconds(timeout))
+                    .build();
+
+            HttpResponse<String> response = client.send(
+                    requestBuilder.build(),
+                    HttpResponse.BodyHandlers.ofString());
+
+            // Try to parse response as JSON, fall back to string
+            Object responseData;
+            try {
+                responseData = GSON.fromJson(response.body(), Object.class);
+            } catch (JsonSyntaxException e) {
+                responseData = response.body();
+            }
+
+            // Collect response headers
+            Map<String, String> responseHeaders = new HashMap<>();
+            response.headers().map().forEach((key, values) -> {
+                if (!values.isEmpty()) {
+                    responseHeaders.put(key, values.get(0));
+                }
+            });
+
+            Map<String, Object> result = new HashMap<>();
+            result.put("status", response.statusCode());
+            result.put("data", responseData);
+            result.put("headers", responseHeaders);
+            return result;
+
+        } catch (Exception e) {
+            if (e instanceof NodeException) {
+                throw e;
+            }
+            throw NodeException.network("request to " + url + " failed: " + e.getMessage(), e);
+        }
+    }
+}