blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/python3/examples/blok_error_demo_node.py

@@ -0,0 +1,79 @@
+"""Example node demonstrating the structured :class:`BlokError` API.
+
+Used by the cross-language E2E test (`python-grpc.integration.test.ts`)
+to verify that a structured Python error flows through the gRPC wire to
+the runner with every field preserved (category, severity, code,
+remediation, retryable hints, cause chain, context snapshot).
+
+Triggers:
+- ``mode="dependency"`` (default) — raises ``BlokError.dependency`` with a
+  cause chain rooted in a ``ConnectionError``.
+- ``mode="rate-limit"`` — raises ``BlokError.rate_limit`` with
+  ``retry_after_ms``.
+- ``mode="validation"`` — raises ``BlokError.validation`` with
+  ``details`` carrying a Zod-style issue list.
+- ``mode="ok"`` — returns success (sanity check the node isn't broken).
+"""
+
+from __future__ import annotations
+from typing import Any, Dict
+
+from blok.errors.blok_error import BlokError, build_context_snapshot
+from blok.node.node_handler import NodeHandler
+from blok.types.context import Context
+
+
+class BlokErrorDemoNode(NodeHandler):
+    """Raises a structured BlokError matching the requested mode."""
+
+    def execute(self, ctx: Context, config: Dict[str, Any]) -> Any:
+        mode = config.get("mode", "dependency")
+
+        if mode == "ok":
+            return {"ok": True, "language": "python3"}
+
+        snapshot = build_context_snapshot(inputs=config, vars_map=ctx.vars)
+
+        if mode == "rate-limit":
+            raise BlokError.rate_limit(
+                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.",
+                retry_after_ms=60_000,
+                doc_url="https://docs.example.com/errors/rate-limit",
+                details={"limit": 5000, "remaining": 0},
+                context_snapshot=snapshot,
+            )
+
+        if mode == "validation":
+            raise 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={
+                    "issues": [
+                        {"path": ["email"], "message": "Required"},
+                        {"path": ["name"], "message": "Required"},
+                    ],
+                },
+                context_snapshot=snapshot,
+            )
+
+        # default: dependency with a cause chain
+        try:
+            raise ConnectionError("[Errno 61] Connection refused")
+        except ConnectionError as exc:
+            raise 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=exc,
+                retryable=True,
+                retry_after_ms=5_000,
+                doc_url="https://docs.example.com/errors/POSTGRES_CONNECT_TIMEOUT",
+                details={"host": "db.internal", "port": 5432, "timeout_ms": 5000},
+                context_snapshot=snapshot,
+            ) from exc

package/dist/scaffold-repo/sdks/python3/examples/chain_test_node.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+from blok.node.node_handler import NodeHandler
+from blok.types.context import Context
+
+
+class ChainTestNode(NodeHandler):
+    """Cross-runtime chain test node for integration testing.
+
+    Reads a chain array from the request body, appends a python3 entry,
+    and returns the updated chain -- proving data flows between languages.
+    """
+
+    def execute(self, ctx: Context, config: Dict[str, Any]) -> Any:
+        body = ctx.request.body_map()
+
+        # 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.
+        chain: list = []
+        if isinstance(config.get("chain"), list):
+            chain = list(config["chain"])
+        elif body and isinstance(body.get("chain"), list):
+            chain = list(body["chain"])
+
+        # Read origin — same dual-read.
+        origin = "unknown"
+        if isinstance(config.get("origin"), str) and config["origin"]:
+            origin = config["origin"]
+        elif body and isinstance(body.get("origin"), str):
+            origin = body["origin"]
+
+        # Append this language's entry
+        entry = {
+            "language": "python3",
+            "order": len(chain) + 1,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        chain.append(entry)
+
+        # Store in context vars
+        ctx.set_var("chain", chain)
+
+        return {
+            "chain": chain,
+            "origin": origin,
+        }

package/dist/scaffold-repo/sdks/python3/examples/hello_world_node.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+from blok.node.node_handler import NodeHandler
+from blok.types.context import Context
+
+# Logger that flows into the runner's RunTracker when BLOK_STREAM_LOGS=true.
+# Reusing the canonical name documented in blok.server.grpc_server.NODE_LOGGER_NAME
+# so handler authors see a consistent convention across examples.
+log = logging.getLogger("blok.node")
+
+
+class HelloWorldNode(NodeHandler):
+    """Greets the user with a configurable prefix.
+
+    Config:
+        prefix (str, optional): Greeting prefix (default: "Hello")
+
+    Request body:
+        name (str, optional): Name to greet (default: "World")
+
+    Output:
+        {"message": "Hello, World!", "timestamp": "...", "language": "python3"}
+    """
+
+    def execute(self, ctx: Context, config: Dict[str, Any]) -> Any:
+        name = ctx.request.body_str("name") or "World"
+        prefix = config.get("prefix", "Hello")
+        message = f"{prefix}, {name}!"
+
+        # Emitted on the `blok.node` logger so the runner's streaming path
+        # forwards it as a LogLine event when BLOK_STREAM_LOGS=true. Harmless
+        # in HTTP/unary mode — the logger is just a normal Python logger.
+        log.info("greeting %s with prefix %r", name, prefix)
+
+        ctx.set_var("greeting", message)
+
+        return {
+            "message": message,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "language": "python3",
+        }

package/dist/scaffold-repo/sdks/python3/examples/transform_data_node.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from typing import Any, Dict
+
+from blok.node.node_handler import NodeHandler
+from blok.types.context import Context
+from blok.errors.node_error import NodeError
+
+
+class TransformDataNode(NodeHandler):
+    """Transforms JSON data based on field mappings.
+
+    Config:
+        mappings (dict, optional): Map of target field -> source field path (dot-notation)
+        include_only (list, optional): Only include these fields in output
+        exclude (list, optional): Exclude these fields from output
+        defaults (dict, optional): Default values for missing fields
+
+    Input: Request body (must be a JSON object)
+    Output: Transformed JSON object
+    """
+
+    def execute(self, ctx: Context, config: Dict[str, Any]) -> Any:
+        body = ctx.request.body_map()
+        if body is None:
+            raise NodeError.validation("request body must be a JSON object")
+
+        result: Dict[str, Any] = {}
+
+        # Apply field mappings if configured
+        mappings = config.get("mappings")
+        if isinstance(mappings, dict):
+            for target_field, source_path in mappings.items():
+                if not isinstance(source_path, str):
+                    continue
+                value = _get_nested_value(body, source_path)
+                if value is not None:
+                    result[target_field] = value
+        else:
+            # No mappings -- copy all fields
+            result = dict(body)
+
+        # Apply include_only filter
+        include_only = config.get("include_only")
+        if isinstance(include_only, list) and include_only:
+            result = {k: v for k, v in result.items() if k in include_only}
+
+        # Apply exclude filter
+        exclude = config.get("exclude")
+        if isinstance(exclude, list):
+            for field in exclude:
+                result.pop(field, None)
+
+        # Apply defaults for missing fields
+        defaults = config.get("defaults")
+        if isinstance(defaults, dict):
+            for k, v in defaults.items():
+                if k not in result:
+                    result[k] = v
+
+        ctx.set_var("transformed_data", result)
+        return result
+
+
+def _get_nested_value(data: Dict[str, Any], path: str) -> Any:
+    """Traverse dot-notation path into nested dicts."""
+    current: Any = data
+    for part in path.split("."):
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+    return current

package/dist/scaffold-repo/sdks/python3/examples/typed_greet_node.py

@@ -0,0 +1,25 @@
+"""Typed greeting node demonstrating the SPEC-B @node contract."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from blok import node
+from blok.types.context import Context
+
+
+class TypedGreetInput(BaseModel):
+    name: str
+    repeat: int = 1
+
+
+class TypedGreetOutput(BaseModel):
+    greeting: str
+    length: int
+
+
+@node("typed-greet", "Typed greeting (SPEC-B contract demo)")
+def typed_greet(ctx: Context, input: TypedGreetInput) -> TypedGreetOutput:
+    repeat = input.repeat if input.repeat > 0 else 1
+    greeting = ("Hello, " + input.name) * repeat
+    return TypedGreetOutput(greeting=greeting, length=len(greeting))

package/dist/scaffold-repo/sdks/python3/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/python3/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blok-blok-python3"
+version = "1.0.0"
+description = "Blok Blok SDK for Python 3 — build workflow nodes as HTTP microservices or gRPC servers"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+
+[project.optional-dependencies]
+# NATS JetStream worker support.
+worker = ["nats-py>=2.9.0"]
+
+# gRPC transport support. The runtime server can speak either HTTP (stdlib) or
+# gRPC; pick at startup via `BLOK_TRANSPORT=http|grpc|both` (default `http`).
+# `Health` is defined inline in `runtime.proto` so we do NOT depend on
+# `grpcio-health-checking` (the standard `grpc.health.v1` package).
+grpc = [
+    "grpcio>=1.60",
+    "protobuf>=4.25",
+]
+
+# Typed node authoring via the `@node` decorator (SPEC-B P2). Optional — legacy
+# Dict-based NodeHandler nodes work without it. Install with `.[typed]` (the
+# runtime image includes it so projects can author typed nodes).
+typed = ["pydantic>=2.0"]
+
+# Test dependencies. Installed via `pip install -e .[test]`.
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pydantic>=2.0",
+]
+
+[project.scripts]
+blok-serve = "bin.serve:main"
+blok-worker = "bin.worker:main"
+
+[tool.setuptools.packages.find]
+include = ["blok*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+asyncio_mode = "auto"

package/dist/scaffold-repo/sdks/python3/requirements.txt

@@ -0,0 +1,17 @@
+# Blok Blok Python3 SDK
+# pydantic powers the typed `@node` authoring contract (SPEC-B P2). Legacy
+# Dict-based NodeHandler nodes work without it, but the runtime ships it so
+# projects can author typed nodes out of the box.
+pydantic>=2.0
+#
+# gRPC transport. Since v0.5 the runner speaks ONLY gRPC (the HTTP
+# `POST /execute` path was removed), so the sidecar always boots in gRPC mode
+# and `bin/serve.py` requires grpcio at startup. These MUST be in the base
+# requirements so `blokctl`'s scaffold venv (`pip install -r requirements.txt`)
+# can start the runtime — mirrors the `[grpc]` extra in pyproject.toml and the
+# Dockerfile. Without them the python3 sidecar fails "requires grpcio".
+grpcio>=1.60
+protobuf>=4.25
+#
+# For worker mode (NATS JetStream background jobs), install:
+#   pip install nats-py>=2.9.0