blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/errors/BuildContextSnapshot.java

@@ -0,0 +1,132 @@
+package com.blok.blok.errors;
+
+import com.google.gson.Gson;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Bounded slice of inputs + recent vars for the
+ * {@code BlokError.contextSnapshot} field, per master plan §17.6.
+ *
+ * <p>Default budget: 4 KB serialized + last-16 vars keys, with progressive
+ * trimming when oversize. {@code inputs} is preserved as-is — it's the most
+ * LLM-actionable context. Mirrors Python's {@code build_context_snapshot},
+ * Go's {@code BuildContextSnapshot}, and Rust's
+ * {@code build_context_snapshot}.
+ */
+public final class BuildContextSnapshot {
+
+    private static final Gson GSON = new Gson();
+
+    private BuildContextSnapshot() {
+        // static helpers only
+    }
+
+    /** Snapshot of {@code inputs} + last-16 vars keys, capped at 4 KB. */
+    public static Map<String, Object> of(Map<String, Object> inputs, Map<String, Object> vars) {
+        return of(inputs, vars, BlokError.CONTEXT_SNAPSHOT_MAX_BYTES, 16);
+    }
+
+    /**
+     * Customizable variant of {@link #of(Map, Map)}.
+     *
+     * <p>{@code maxVarsKeys = 0} drops vars entirely.
+     * {@code maxBytes <= 0} disables byte-budget trimming.
+     */
+    public static Map<String, Object> of(
+            Map<String, Object> inputs,
+            Map<String, Object> vars,
+            int maxBytes,
+            int maxVarsKeys
+    ) {
+        Map<String, Object> safeInputs = jsonSafeMap(inputs);
+
+        // Use TreeMap to give a deterministic "last N" slice (Java HashMap
+        // iteration order isn't guaranteed). LLM/Studio consumers don't care
+        // about ordering, but tests do.
+        TreeMap<String, Object> sorted = new TreeMap<>(vars != null ? vars : Map.of());
+        List<String> keys = new ArrayList<>(sorted.keySet());
+        if (maxVarsKeys >= 0 && keys.size() > maxVarsKeys) {
+            keys = keys.subList(keys.size() - maxVarsKeys, keys.size());
+        }
+
+        Map<String, Object> recent = new LinkedHashMap<>();
+        for (String k : keys) recent.put(k, jsonSafe(sorted.get(k)));
+
+        Map<String, Object> snapshot = new LinkedHashMap<>();
+        snapshot.put("inputs", safeInputs);
+        snapshot.put("vars", recent);
+
+        if (maxBytes <= 0) {
+            return snapshot;
+        }
+
+        if (encodedBytes(snapshot) <= maxBytes) {
+            return snapshot;
+        }
+
+        // Trim from the front (oldest keys) until the snapshot fits.
+        while (!keys.isEmpty()) {
+            keys = keys.subList(1, keys.size());
+            recent = new LinkedHashMap<>();
+            for (String k : keys) recent.put(k, jsonSafe(sorted.get(k)));
+            snapshot.put("vars", recent);
+            if (encodedBytes(snapshot) <= maxBytes) {
+                return snapshot;
+            }
+        }
+
+        Map<String, Object> truncated = new LinkedHashMap<>();
+        truncated.put("inputs", safeInputs);
+        truncated.put("vars", new LinkedHashMap<>());
+        truncated.put("_truncated", true);
+        return truncated;
+    }
+
+    private static int encodedBytes(Object value) {
+        return GSON.toJson(value).getBytes(StandardCharsets.UTF_8).length;
+    }
+
+    private static Map<String, Object> jsonSafeMap(Map<String, Object> m) {
+        Map<String, Object> out = new LinkedHashMap<>();
+        if (m == null) return out;
+        for (Map.Entry<String, Object> e : m.entrySet()) {
+            out.put(e.getKey(), jsonSafe(e.getValue()));
+        }
+        return out;
+    }
+
+    @SuppressWarnings("unchecked")
+    private static Object jsonSafe(Object v) {
+        if (v == null
+                || v instanceof String
+                || v instanceof Number
+                || v instanceof Boolean) {
+            return v;
+        }
+        if (v instanceof Map<?, ?> raw) {
+            Map<String, Object> sm = new LinkedHashMap<>();
+            for (Map.Entry<?, ?> e : raw.entrySet()) {
+                sm.put(String.valueOf(e.getKey()), jsonSafe(e.getValue()));
+            }
+            return sm;
+        }
+        if (v instanceof List<?> list) {
+            List<Object> out = new ArrayList<>(list.size());
+            for (Object x : list) out.add(jsonSafe(x));
+            return out;
+        }
+        // Anything else — try a JSON round-trip via Gson; on failure fall
+        // back to the toString() representation.
+        try {
+            return GSON.fromJson(GSON.toJson(v), Object.class);
+        } catch (Exception ex) {
+            return String.valueOf(v);
+        }
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/errors/ErrorCategory.java

@@ -0,0 +1,22 @@
+package com.blok.blok.errors;
+
+/**
+ * Classifies the type of error that occurred during node execution.
+ */
+public enum ErrorCategory {
+
+    /** Schema or input validation failure. */
+    VALIDATION,
+
+    /** Error during node execution. */
+    EXECUTION,
+
+    /** Misconfiguration of node or server. */
+    CONFIGURATION,
+
+    /** Network or connectivity issue. */
+    NETWORK,
+
+    /** Requested resource was not found. */
+    NOT_FOUND
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/errors/NodeException.java

@@ -0,0 +1,176 @@
+package com.blok.blok.errors;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Structured exception for node execution errors.
+ * Carries an error code, category, and optional detail map.
+ */
+public class NodeException extends Exception {
+
+    private final int code;
+    private final ErrorCategory category;
+    private final Map<String, Object> details;
+
+    /**
+     * Constructs a NodeException with full details.
+     *
+     * @param message  the error message
+     * @param code     the HTTP-style error code
+     * @param category the error category
+     * @param details  additional error details (may be null)
+     */
+    public NodeException(String message, int code, ErrorCategory category, Map<String, Object> details) {
+        super(message != null ? message : "unknown error");
+        this.code = code;
+        this.category = category != null ? category : ErrorCategory.EXECUTION;
+        this.details = details;
+    }
+
+    /**
+     * Constructs a NodeException with a cause.
+     *
+     * @param message  the error message
+     * @param code     the HTTP-style error code
+     * @param category the error category
+     * @param details  additional error details (may be null)
+     * @param cause    the underlying cause
+     */
+    public NodeException(String message, int code, ErrorCategory category, Map<String, Object> details, Throwable cause) {
+        super(message != null ? message : "unknown error", cause);
+        this.code = code;
+        this.category = category != null ? category : ErrorCategory.EXECUTION;
+        this.details = details;
+    }
+
+    // Factory methods
+
+    /**
+     * Creates a validation error (HTTP 400).
+     *
+     * @param message the error message
+     * @return a NodeException with VALIDATION category
+     */
+    public static NodeException validation(String message) {
+        return new NodeException(message, 400, ErrorCategory.VALIDATION, null);
+    }
+
+    /**
+     * Creates an execution error (HTTP 500).
+     *
+     * @param message the error message
+     * @return a NodeException with EXECUTION category
+     */
+    public static NodeException execution(String message) {
+        return new NodeException(message, 500, ErrorCategory.EXECUTION, null);
+    }
+
+    /**
+     * Creates an execution error with a cause (HTTP 500).
+     *
+     * @param message the error message
+     * @param cause   the underlying cause
+     * @return a NodeException with EXECUTION category
+     */
+    public static NodeException execution(String message, Throwable cause) {
+        return new NodeException(message, 500, ErrorCategory.EXECUTION, null, cause);
+    }
+
+    /**
+     * Creates a configuration error (HTTP 500).
+     *
+     * @param message the error message
+     * @return a NodeException with CONFIGURATION category
+     */
+    public static NodeException configuration(String message) {
+        return new NodeException(message, 500, ErrorCategory.CONFIGURATION, null);
+    }
+
+    /**
+     * Creates a network error (HTTP 502).
+     *
+     * @param message the error message
+     * @return a NodeException with NETWORK category
+     */
+    public static NodeException network(String message) {
+        return new NodeException(message, 502, ErrorCategory.NETWORK, null);
+    }
+
+    /**
+     * Creates a network error with a cause (HTTP 502).
+     *
+     * @param message the error message
+     * @param cause   the underlying cause
+     * @return a NodeException with NETWORK category
+     */
+    public static NodeException network(String message, Throwable cause) {
+        return new NodeException(message, 502, ErrorCategory.NETWORK, null, cause);
+    }
+
+    /**
+     * Creates a not-found error (HTTP 404).
+     *
+     * @param message the error message
+     * @return a NodeException with NOT_FOUND category
+     */
+    public static NodeException notFound(String message) {
+        return new NodeException(message, 404, ErrorCategory.NOT_FOUND, null);
+    }
+
+    /**
+     * Converts this exception to a map for serialization in ExecutionResult.
+     *
+     * @return the error as a map
+     */
+    public Map<String, Object> toMap() {
+        Map<String, Object> map = new HashMap<>();
+        map.put("message", getMessage());
+        map.put("code", code);
+        map.put("category", category.name());
+        if (details != null && !details.isEmpty()) {
+            map.put("details", details);
+        }
+        if (getCause() != null) {
+            map.put("cause", getCause().getMessage());
+        }
+        return map;
+    }
+
+    // Getters
+
+    public int getCode() {
+        return code;
+    }
+
+    public ErrorCategory getCategory() {
+        return category;
+    }
+
+    public Map<String, Object> getDetails() {
+        return details;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        NodeException that = (NodeException) o;
+        return code == that.code &&
+                Objects.equals(getMessage(), that.getMessage()) &&
+                category == that.category &&
+                Objects.equals(details, that.details);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(getMessage(), code, category, details);
+    }
+
+    @Override
+    public String toString() {
+        return "[" + category + "] " + getMessage() +
+                (getCause() != null ? ": " + getCause().getMessage() : "");
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/logging/LogEntry.java

@@ -0,0 +1,78 @@
+package com.blok.blok.logging;
+
+import com.google.gson.Gson;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Represents a single structured log entry.
+ */
+public class LogEntry {
+
+    private final LogLevel level;
+    private final String message;
+    private final Instant timestamp;
+    private final Map<String, Object> fields;
+
+    public LogEntry(LogLevel level, String message, Instant timestamp, Map<String, Object> fields) {
+        this.level = level != null ? level : LogLevel.INFO;
+        this.message = message != null ? message : "";
+        this.timestamp = timestamp != null ? timestamp : Instant.now();
+        this.fields = fields;
+    }
+
+    public LogLevel getLevel() {
+        return level;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public Instant getTimestamp() {
+        return timestamp;
+    }
+
+    public Map<String, Object> getFields() {
+        return fields;
+    }
+
+    /**
+     * Formats this entry as a human-readable string.
+     *
+     * @return formatted log line
+     */
+    public String format() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("[").append(level).append("] ");
+        sb.append(timestamp.toString()).append(" ");
+        sb.append(message);
+        if (fields != null && !fields.isEmpty()) {
+            sb.append(" ").append(new Gson().toJson(fields));
+        }
+        return sb.toString();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        LogEntry logEntry = (LogEntry) o;
+        return level == logEntry.level &&
+                Objects.equals(message, logEntry.message) &&
+                Objects.equals(timestamp, logEntry.timestamp) &&
+                Objects.equals(fields, logEntry.fields);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(level, message, timestamp, fields);
+    }
+
+    @Override
+    public String toString() {
+        return format();
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/logging/LogLevel.java

@@ -0,0 +1,48 @@
+package com.blok.blok.logging;
+
+/**
+ * Log severity levels with priority ordering.
+ * Higher priority values indicate more severe levels.
+ */
+public enum LogLevel {
+
+    DEBUG(0),
+    INFO(1),
+    WARN(2),
+    ERROR(3);
+
+    private final int priority;
+
+    LogLevel(int priority) {
+        this.priority = priority;
+    }
+
+    /**
+     * Returns the priority value for this level.
+     * Higher values are more severe.
+     *
+     * @return the priority
+     */
+    public int getPriority() {
+        return priority;
+    }
+
+    /**
+     * Parses a log level from a string, case-insensitive.
+     * Returns the default level if the string is not recognized.
+     *
+     * @param value        the string to parse
+     * @param defaultLevel the fallback level
+     * @return the parsed log level
+     */
+    public static LogLevel fromString(String value, LogLevel defaultLevel) {
+        if (value == null || value.isBlank()) {
+            return defaultLevel;
+        }
+        try {
+            return LogLevel.valueOf(value.trim().toUpperCase());
+        } catch (IllegalArgumentException e) {
+            return defaultLevel;
+        }
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/logging/Logger.java

@@ -0,0 +1,160 @@
+package com.blok.blok.logging;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Structured logger with a capture buffer.
+ * Log entries are captured in memory and can be retrieved via {@link #lines()}
+ * for inclusion in {@code ExecutionResult.logs}.
+ * <p>
+ * Thread-safe: all operations on the entry buffer are synchronized.
+ */
+public class Logger {
+
+    private final LogLevel minLevel;
+    private final List<LogEntry> entries;
+
+    /**
+     * Creates a new logger with the specified minimum log level.
+     *
+     * @param minLevel the minimum severity level to capture
+     */
+    public Logger(LogLevel minLevel) {
+        this.minLevel = minLevel != null ? minLevel : LogLevel.INFO;
+        this.entries = new ArrayList<>();
+    }
+
+    /**
+     * Returns whether the given level meets the minimum threshold.
+     *
+     * @param level the level to check
+     * @return true if the level should be logged
+     */
+    public boolean shouldLog(LogLevel level) {
+        if (level == null) return false;
+        return level.getPriority() >= minLevel.getPriority();
+    }
+
+    private void log(LogLevel level, String message, Map<String, Object> fields) {
+        if (!shouldLog(level)) {
+            return;
+        }
+        LogEntry entry = new LogEntry(level, message, Instant.now(), fields);
+        synchronized (entries) {
+            entries.add(entry);
+        }
+    }
+
+    /**
+     * Logs a DEBUG-level message.
+     *
+     * @param message the message
+     */
+    public void debug(String message) {
+        log(LogLevel.DEBUG, message, null);
+    }
+
+    /**
+     * Logs a DEBUG-level message with fields.
+     *
+     * @param message the message
+     * @param fields  additional structured fields
+     */
+    public void debug(String message, Map<String, Object> fields) {
+        log(LogLevel.DEBUG, message, fields);
+    }
+
+    /**
+     * Logs an INFO-level message.
+     *
+     * @param message the message
+     */
+    public void info(String message) {
+        log(LogLevel.INFO, message, null);
+    }
+
+    /**
+     * Logs an INFO-level message with fields.
+     *
+     * @param message the message
+     * @param fields  additional structured fields
+     */
+    public void info(String message, Map<String, Object> fields) {
+        log(LogLevel.INFO, message, fields);
+    }
+
+    /**
+     * Logs a WARN-level message.
+     *
+     * @param message the message
+     */
+    public void warn(String message) {
+        log(LogLevel.WARN, message, null);
+    }
+
+    /**
+     * Logs a WARN-level message with fields.
+     *
+     * @param message the message
+     * @param fields  additional structured fields
+     */
+    public void warn(String message, Map<String, Object> fields) {
+        log(LogLevel.WARN, message, fields);
+    }
+
+    /**
+     * Logs an ERROR-level message.
+     *
+     * @param message the message
+     */
+    public void error(String message) {
+        log(LogLevel.ERROR, message, null);
+    }
+
+    /**
+     * Logs an ERROR-level message with fields.
+     *
+     * @param message the message
+     * @param fields  additional structured fields
+     */
+    public void error(String message, Map<String, Object> fields) {
+        log(LogLevel.ERROR, message, fields);
+    }
+
+    /**
+     * Returns a copy of all captured log entries.
+     *
+     * @return list of log entries
+     */
+    public List<LogEntry> entries() {
+        synchronized (entries) {
+            return new ArrayList<>(entries);
+        }
+    }
+
+    /**
+     * Returns all log entries as formatted strings for {@code ExecutionResult.logs}.
+     *
+     * @return list of formatted log lines
+     */
+    public List<String> lines() {
+        List<LogEntry> snapshot = entries();
+        List<String> result = new ArrayList<>(snapshot.size());
+        for (LogEntry entry : snapshot) {
+            result.add(entry.format());
+        }
+        return result;
+    }
+
+    /**
+     * Clears all captured log entries.
+     */
+    public void clear() {
+        synchronized (entries) {
+            entries.clear();
+        }
+    }
+}

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

@@ -0,0 +1,65 @@
+package com.blok.blok.middleware;
+
+import com.blok.blok.logging.Logger;
+import com.blok.blok.node.NodeHandler;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Middleware that logs node execution start and end with timing information.
+ */
+public class LoggingMiddleware implements Middleware {
+
+    private final Logger logger;
+
+    /**
+     * Creates a LoggingMiddleware with the given logger.
+     *
+     * @param logger the logger to write to
+     * @throws IllegalArgumentException if logger is null
+     */
+    public LoggingMiddleware(Logger logger) {
+        if (logger == null) {
+            throw new IllegalArgumentException("logger must not be null");
+        }
+        this.logger = logger;
+    }
+
+    @Override
+    public NodeHandler wrap(NodeHandler next) {
+        return (ctx, config) -> {
+            long start = System.nanoTime();
+
+            Map<String, Object> startFields = new HashMap<>();
+            startFields.put("workflow", ctx.getWorkflowName());
+            logger.info("node execution started", startFields);
+
+            try {
+                Object result = next.execute(ctx, config);
+
+                long durationNanos = System.nanoTime() - start;
+                double durationMs = durationNanos / 1_000_000.0;
+
+                Map<String, Object> endFields = new HashMap<>();
+                endFields.put("workflow", ctx.getWorkflowName());
+                endFields.put("duration_ms", durationMs);
+                logger.info("node execution completed", endFields);
+
+                return result;
+
+            } catch (Exception e) {
+                long durationNanos = System.nanoTime() - start;
+                double durationMs = durationNanos / 1_000_000.0;
+
+                Map<String, Object> errorFields = new HashMap<>();
+                errorFields.put("workflow", ctx.getWorkflowName());
+                errorFields.put("duration_ms", durationMs);
+                errorFields.put("error", e.getMessage());
+                logger.error("node execution failed", errorFields);
+
+                throw e;
+            }
+        };
+    }
+}