blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/python3/tests/test_blok_error.py

@@ -0,0 +1,341 @@
+"""Unit tests for the structured :class:`BlokError`.
+
+Covers:
+- 12 category factories return the right category + http_status + retryable
+- Constructor option overrides (severity, retryable, retry_after_ms, etc.)
+- ``from_unknown`` heuristics for BlokError, Exception, dict, str, None,
+  and arbitrary values
+- ``to_dict`` / ``from_dict`` lossless round-trip
+- Cause-chain flattening (cycle-safe, BlokError-as-cause flattens not nests)
+- ``build_context_snapshot`` bounded-slice behavior
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from blok.errors.blok_error import (
+    BlokError,
+    CONTEXT_SNAPSHOT_MAX_BYTES,
+    DEFAULT_HTTP_STATUS,
+    DEFAULT_RETRYABLE,
+    DEFAULT_RUNTIME_KIND,
+    DEFAULT_SDK_NAME,
+    ErrorCategory,
+    ErrorSeverity,
+    build_context_snapshot,
+)
+
+
+# =============================================================================
+# Category factories
+# =============================================================================
+
+
+@pytest.mark.parametrize(
+    "factory,category",
+    [
+        (BlokError.validation, ErrorCategory.VALIDATION),
+        (BlokError.configuration, ErrorCategory.CONFIGURATION),
+        (BlokError.dependency, ErrorCategory.DEPENDENCY),
+        (BlokError.timeout, ErrorCategory.TIMEOUT),
+        (BlokError.permission, ErrorCategory.PERMISSION),
+        (BlokError.rate_limit, ErrorCategory.RATE_LIMIT),
+        (BlokError.not_found, ErrorCategory.NOT_FOUND),
+        (BlokError.conflict, ErrorCategory.CONFLICT),
+        (BlokError.cancelled, ErrorCategory.CANCELLED),
+        (BlokError.internal, ErrorCategory.INTERNAL),
+        (BlokError.protocol, ErrorCategory.PROTOCOL),
+        (BlokError.data, ErrorCategory.DATA),
+    ],
+)
+def test_factory_sets_correct_category_and_defaults(factory, category):
+    err = factory(code="TEST", message="m")
+    assert err.category == category
+    assert err.code == "TEST"
+    assert err.message == "m"
+    assert err.http_status == DEFAULT_HTTP_STATUS[category]
+    assert err.retryable == DEFAULT_RETRYABLE[category]
+    assert err.severity == ErrorSeverity.ERROR
+
+
+def test_factory_options_override_defaults():
+    err = BlokError.dependency(
+        code="POSTGRES_DOWN",
+        message="db down",
+        description="long story",
+        remediation="restart it",
+        doc_url="https://example.com/x",
+        retryable=False,
+        retry_after_ms=10_000,
+        details={"sql_state": "08001"},
+        http_status=503,
+        severity=ErrorSeverity.FATAL,
+    )
+    assert err.retryable is False  # override the default True
+    assert err.http_status == 503  # override default 502
+    assert err.severity == ErrorSeverity.FATAL
+    assert err.description == "long story"
+    assert err.remediation == "restart it"
+    assert err.doc_url == "https://example.com/x"
+    assert err.retry_after_ms == 10_000
+    assert err.details == {"sql_state": "08001"}
+
+
+def test_blok_error_is_a_python_exception():
+    err = BlokError.validation(code="X", message="bad")
+    assert isinstance(err, BlokError)
+    assert isinstance(err, Exception)
+    assert str(err) == "bad"
+
+
+def test_at_is_utc_datetime():
+    err = BlokError.internal(code="X", message="m")
+    assert err.at.tzinfo is not None  # timezone-aware
+
+
+# =============================================================================
+# from_unknown heuristics
+# =============================================================================
+
+
+class TestFromUnknown:
+    def test_passes_through_existing_blok_error(self):
+        original = BlokError.dependency(code="X", message="m")
+        wrapped = BlokError.from_unknown(original)
+        assert wrapped is original
+
+    def test_enriches_missing_origin_fields_on_passthrough(self):
+        original = BlokError.dependency(code="X", message="m")
+        wrapped = BlokError.from_unknown(
+            original,
+            node="step-x",
+            sdk="blok-python3",
+            sdk_version="1.0.0",
+            runtime_kind="runtime.python3",
+        )
+        assert wrapped.node == "step-x"
+        assert wrapped.sdk == "blok-python3"
+        assert wrapped.sdk_version == "1.0.0"
+        assert wrapped.runtime_kind == "runtime.python3"
+
+    def test_does_not_overwrite_explicit_origin_fields(self):
+        original = BlokError.dependency(code="X", message="m", node="explicit")
+        wrapped = BlokError.from_unknown(original, node="from-ctx")
+        assert wrapped.node == "explicit"
+
+    def test_wraps_value_error_with_uncaught_typename_code(self):
+        wrapped = BlokError.from_unknown(ValueError("bad number"))
+        assert wrapped.category == ErrorCategory.INTERNAL
+        assert wrapped.code == "UNCAUGHT_VALUEERROR"
+        assert wrapped.message == "bad number"
+        # cause chain has the original exception payload
+        assert len(wrapped.causes) == 1
+        assert wrapped.causes[0]["code"] == "UNCAUGHT_VALUEERROR"
+
+    def test_wraps_dict_extracting_message_and_preserving_payload(self):
+        wrapped = BlokError.from_unknown({"message": "boom", "extra": 42})
+        assert wrapped.code == "UNCAUGHT_ERROR"
+        assert wrapped.message == "boom"
+        assert wrapped.details == {"message": "boom", "extra": 42}
+
+    def test_wraps_dict_without_message_uses_placeholder(self):
+        wrapped = BlokError.from_unknown({"only": "fields"})
+        assert wrapped.message == "node error"
+
+    def test_wraps_string_with_payload_in_details(self):
+        wrapped = BlokError.from_unknown("plain")
+        assert wrapped.message == "plain"
+        assert wrapped.details == {"message": "plain"}
+
+    def test_wraps_none_with_placeholder(self):
+        wrapped = BlokError.from_unknown(None)
+        assert wrapped.code == "UNCAUGHT_ERROR"
+        assert wrapped.message == "node error"
+
+    def test_wraps_arbitrary_value_via_json_dumps(self):
+        wrapped = BlokError.from_unknown(42)
+        assert wrapped.code == "UNCAUGHT_ERROR"
+        assert wrapped.message == "42"
+
+
+# =============================================================================
+# to_dict / from_dict round-trip
+# =============================================================================
+
+
+def test_to_dict_emits_proto_wire_shape():
+    err = BlokError.dependency(
+        code="POSTGRES_DOWN",
+        message="db down",
+        description="long story",
+        remediation="restart it",
+        retryable=True,
+        retry_after_ms=5000,
+        details={"sql_state": "08001"},
+        node="step-1",
+        sdk="blok-python3",
+        sdk_version="1.0.0",
+        runtime_kind="runtime.python3",
+    )
+    d = err.to_dict()
+    assert d["code"] == "POSTGRES_DOWN"
+    assert d["category"] == "DEPENDENCY"
+    assert d["severity"] == "ERROR"
+    assert d["http_status"] == 502
+    assert d["retryable"] is True
+    assert d["retry_after_ms"] == 5000
+    assert d["details"] == {"sql_state": "08001"}
+    assert d["node"] == "step-1"
+    assert d["sdk"] == "blok-python3"
+    # `at` is serialized as ISO 8601 string.
+    assert isinstance(d["at"], str)
+
+
+def test_from_dict_reconstructs_full_payload():
+    original = BlokError.dependency(
+        code="POSTGRES_DOWN",
+        message="db down",
+        description="long story",
+        remediation="restart it",
+        retryable=False,
+        retry_after_ms=5000,
+        details={"sql_state": "08001"},
+        http_status=503,
+        node="step-1",
+    )
+    payload = original.to_dict()
+    reconstructed = BlokError.from_dict(payload)
+
+    assert reconstructed.category == ErrorCategory.DEPENDENCY
+    assert reconstructed.code == "POSTGRES_DOWN"
+    assert reconstructed.message == "db down"
+    assert reconstructed.description == "long story"
+    assert reconstructed.remediation == "restart it"
+    assert reconstructed.retryable is False
+    assert reconstructed.retry_after_ms == 5000
+    assert reconstructed.details == {"sql_state": "08001"}
+    assert reconstructed.http_status == 503
+    assert reconstructed.node == "step-1"
+
+
+def test_from_dict_handles_camelcase_and_unknown_categories():
+    # Mirrors the TS payload shape (camelCase) so cross-language round-trips
+    # via the proto JSON form work.
+    payload = {
+        "code": "X",
+        "category": "weird-category",  # falls back to INTERNAL
+        "severity": "huh",  # falls back to ERROR
+        "message": "m",
+        "httpStatus": 418,
+        "retryAfterMs": 1000,
+        "sdkVersion": "9.9.9",
+        "runtimeKind": "runtime.python3",
+        "docUrl": "https://example.com",
+        "contextSnapshot": {"x": 1},
+    }
+    err = BlokError.from_dict(payload)
+    assert err.category == ErrorCategory.INTERNAL
+    assert err.severity == ErrorSeverity.ERROR
+    assert err.http_status == 418
+    assert err.retry_after_ms == 1000
+    assert err.sdk_version == "9.9.9"
+    assert err.runtime_kind == "runtime.python3"
+    assert err.doc_url == "https://example.com"
+    assert err.context_snapshot == {"x": 1}
+
+
+# =============================================================================
+# Cause chain flattening
+# =============================================================================
+
+
+def test_cause_chain_for_plain_exception():
+    err = BlokError.dependency(
+        code="X",
+        message="outer",
+        cause=ValueError("inner"),
+    )
+    assert len(err.causes) == 1
+    assert err.causes[0]["code"] == "UNCAUGHT_VALUEERROR"
+    assert err.causes[0]["message"] == "inner"
+
+
+def test_cause_chain_for_blok_error_flattens_not_nests():
+    leaf = BlokError.dependency(
+        code="LEAF",
+        message="leaf",
+        cause=RuntimeError("root"),
+    )
+    middle = BlokError.dependency(code="MID", message="mid", cause=leaf)
+
+    # `middle.causes` should contain leaf's payload + leaf's flattened causes,
+    # NOT a single nested cause object with cause inside cause.
+    assert len(middle.causes) == 2
+    assert middle.causes[0]["code"] == "LEAF"
+    assert middle.causes[0]["causes"] == []
+    assert middle.causes[1]["code"] == "UNCAUGHT_RUNTIMEERROR"
+
+
+def test_cause_chain_is_cycle_safe():
+    err1 = ValueError("a")
+    err2 = RuntimeError("b")
+    err1.__cause__ = err2
+    err2.__cause__ = err1  # cycle
+    err = BlokError.from_unknown(err1)
+    # The walker stops on cycle detection; we get at most 2 entries.
+    assert len(err.causes) <= 2
+
+
+# =============================================================================
+# Context snapshot helper
+# =============================================================================
+
+
+class TestBuildContextSnapshot:
+    def test_empty_inputs_and_vars(self):
+        snap = build_context_snapshot(inputs={}, vars_map={})
+        assert snap == {"inputs": {}, "vars": {}}
+
+    def test_includes_all_inputs_and_recent_vars(self):
+        inputs = {"prefix": "Hi"}
+        vars_map = {f"step{i}": {"value": i} for i in range(20)}
+        snap = build_context_snapshot(inputs=inputs, vars_map=vars_map, max_vars_keys=16)
+        assert snap["inputs"] == inputs
+        # Last 16 keys win.
+        assert len(snap["vars"]) == 16
+        assert "step19" in snap["vars"]
+        assert "step3" not in snap["vars"]
+        assert "step4" in snap["vars"]
+
+    def test_trims_vars_when_payload_exceeds_max_bytes(self):
+        big_vars = {f"k{i}": "x" * 200 for i in range(30)}
+        snap = build_context_snapshot(
+            inputs={"shape": "round"},
+            vars_map=big_vars,
+            max_bytes=1024,
+            max_vars_keys=30,
+        )
+        encoded = json.dumps(snap, default=str).encode("utf-8")
+        assert len(encoded) <= 1024
+        assert snap["inputs"] == {"shape": "round"}
+
+    def test_handles_non_json_serializable_values_via_repr(self):
+        class Foo:
+            def __repr__(self):
+                return "<Foo>"
+
+        snap = build_context_snapshot(inputs={"obj": Foo()}, vars_map={})
+        assert snap["inputs"]["obj"] == "<Foo>"
+
+
+# =============================================================================
+# Auto-enrichment defaults exposed
+# =============================================================================
+
+
+def test_default_sdk_constants():
+    assert DEFAULT_SDK_NAME == "blok-python3"
+    assert DEFAULT_RUNTIME_KIND == "runtime.python3"
+    assert CONTEXT_SNAPSHOT_MAX_BYTES == 4096

package/dist/scaffold-repo/sdks/python3/tests/test_define_node.py

@@ -0,0 +1,135 @@
+"""Tests for the typed `@node` contract (SPEC-B P2)."""
+
+import json
+
+import pytest
+from pydantic import BaseModel, Field
+
+from blok import Context, node
+from blok.errors.blok_error import BlokError
+from blok.node.define_node import (
+    _reset_decorated_for_tests,
+    register_decorated,
+    registered_nodes,
+)
+from blok.node.node_registry import NodeRegistry
+from blok.server.grpc_server import _node_schema_bytes
+
+
+class _Input(BaseModel):
+    query: str = Field(min_length=1)
+    limit: int = Field(10, ge=1, le=100)
+
+
+class _Output(BaseModel):
+    results: list[str]
+    count: int
+
+
+@pytest.fixture(autouse=True)
+def _isolate():
+    _reset_decorated_for_tests()
+    yield
+    _reset_decorated_for_tests()
+
+
+def _ctx() -> Context:
+    return Context(id="t", workflow_name="wf", workflow_path="/wf")
+
+
+def test_validates_input_and_serializes_output():
+    @node(name="@acme/search", description="Full-text search")
+    def search(ctx: Context, inp: _Input) -> _Output:
+        assert isinstance(inp, _Input)  # validated, typed — not a raw dict
+        return _Output(results=[inp.query] * inp.limit, count=inp.limit)
+
+    out = search.execute(_ctx(), {"query": "ada", "limit": 2})
+    assert out == {"results": ["ada", "ada"], "count": 2}  # serialized dict
+
+
+def test_applies_pydantic_defaults():
+    @node(name="@acme/d")
+    def d(ctx: Context, inp: _Input) -> _Output:
+        return _Output(results=[], count=inp.limit)
+
+    out = d.execute(_ctx(), {"query": "x"})  # limit omitted → default 10
+    assert out["count"] == 10
+
+
+def test_invalid_input_raises_structured_blok_error():
+    @node(name="@acme/search2")
+    def search(ctx: Context, inp: _Input) -> _Output:
+        return _Output(results=[], count=0)
+
+    with pytest.raises(BlokError) as ei:
+        search.execute(_ctx(), {"limit": 999})  # missing query + limit out of range
+    err = ei.value
+    assert err.code == "NODE_INPUT_VALIDATION"
+    assert err.http_status == 400
+    assert "query" in str(err.message)
+
+
+def test_invalid_output_raises():
+    @node(name="@acme/bado")
+    def bad(ctx: Context, inp: _Input) -> _Output:
+        return {"results": "not-a-list", "count": "nope"}  # wrong shape
+
+    with pytest.raises(BlokError) as ei:
+        bad.execute(_ctx(), {"query": "x"})
+    assert ei.value.code == "NODE_OUTPUT_VALIDATION"
+
+
+def test_untyped_node_passes_dict_through():
+    @node(name="@acme/raw")  # no model annotations
+    def raw(ctx, config):
+        return {"echo": config.get("a")}
+
+    assert raw.execute(_ctx(), {"a": 1}) == {"echo": 1}
+
+
+def test_reflection_schemas():
+    @node(name="@acme/r")
+    def r(ctx: Context, inp: _Input) -> _Output:
+        return _Output(results=[], count=0)
+
+    inp_schema = r.input_json_schema()
+    assert inp_schema["type"] == "object"
+    assert "query" in inp_schema["properties"]
+    out_schema = r.output_json_schema()
+    assert out_schema["properties"]["count"]["type"] == "integer"
+
+
+def test_auto_registration():
+    @node(name="@acme/a")
+    def a(ctx: Context, inp: _Input) -> _Output:
+        return _Output(results=[], count=0)
+
+    @node(name="@acme/b", register=False)  # opt out
+    def b(ctx: Context, inp: _Input) -> _Output:
+        return _Output(results=[], count=0)
+
+    names = [h.name for h in registered_nodes()]
+    assert "@acme/a" in names
+    assert "@acme/b" not in names
+
+    registry = NodeRegistry()
+    count = register_decorated(registry)
+    assert count == 1
+    assert registry.get("@acme/a") is not None
+
+
+def test_listnodes_schema_bytes_for_typed_and_legacy():
+    @node(name="@acme/typed")
+    def typed(ctx: Context, inp: _Input) -> _Output:
+        return _Output(results=[], count=0)
+
+    # Typed node → real JSON Schema bytes.
+    raw = _node_schema_bytes(typed, "input_json_schema")
+    assert raw != b""
+    assert json.loads(raw)["type"] == "object"
+
+    # A legacy handler without the reflection method → empty bytes.
+    class Legacy:
+        description = "legacy"
+
+    assert _node_schema_bytes(Legacy(), "input_json_schema") == b""

package/dist/scaffold-repo/sdks/python3/tests/test_discovery.py

@@ -0,0 +1,99 @@
+"""Tests for user-node discovery (`load_user_nodes`) — the Python on-ramp.
+
+`blokctl create node` scaffolds an `@node` into `runtimes/python3/nodes/<name>/`;
+the runtime discovers + registers it at boot via `BLOK_NODES_DIR`.
+"""
+
+import pytest
+
+from blok import Context
+from blok.node.define_node import _reset_decorated_for_tests, load_user_nodes
+from blok.node.node_registry import NodeRegistry
+
+_SCAFFOLD = """\
+from pydantic import BaseModel
+
+from blok import node
+from blok.types.context import Context
+
+
+class Input(BaseModel):
+    name: str = "world"
+
+
+class Output(BaseModel):
+    message: str
+
+
+@node("my-greeter", "demo")
+def run(ctx: Context, input: Input) -> Output:
+    return Output(message=f"Hello, {input.name}!")
+"""
+
+
+@pytest.fixture(autouse=True)
+def _isolate():
+    _reset_decorated_for_tests()
+    yield
+    _reset_decorated_for_tests()
+
+
+def _write_node(nodes_dir, name: str, body: str) -> None:
+    node_dir = nodes_dir / name
+    node_dir.mkdir(parents=True)
+    (node_dir / "node.py").write_text(body)
+    (node_dir / "__init__.py").write_text("")
+
+
+def test_discovers_registers_and_executes(tmp_path):
+    _write_node(tmp_path, "my-greeter", _SCAFFOLD)
+
+    registry = NodeRegistry()
+    count = load_user_nodes(registry, str(tmp_path))
+
+    assert count == 1
+    assert "my-greeter" in registry.node_names()
+
+    # The registered handler validates input and serializes typed output.
+    handler = registry.get("my-greeter")
+    assert handler is not None
+    assert handler.execute(Context(id="t", workflow_name="wf", workflow_path="/wf"), {"name": "Blok"}) == {
+        "message": "Hello, Blok!"
+    }
+
+
+def test_missing_or_unset_dir_is_noop():
+    registry = NodeRegistry()
+    assert load_user_nodes(registry, None) == 0
+    assert load_user_nodes(registry, "/no/such/dir/xyz") == 0
+    assert registry.node_names() == []
+
+
+def test_only_new_handlers_registered_is_additive(tmp_path):
+    # A handler collected BEFORE the call (e.g. an SDK example) must not be
+    # re-registered by load_user_nodes — only nodes discovered this call count.
+    from blok import node
+
+    @node("pre-existing", "already collected")
+    def _pre(ctx, _input):  # noqa: ANN001
+        return {}
+
+    _write_node(tmp_path, "fresh", _SCAFFOLD.replace("my-greeter", "fresh"))
+
+    registry = NodeRegistry()
+    count = load_user_nodes(registry, str(tmp_path))
+
+    assert count == 1  # only "fresh", not "pre-existing"
+    assert "fresh" in registry.node_names()
+    assert "pre-existing" not in registry.node_names()
+
+
+def test_bad_node_is_skipped_not_fatal(tmp_path):
+    _write_node(tmp_path, "broken", "raise RuntimeError('boom')\n")
+    _write_node(tmp_path, "good", _SCAFFOLD.replace("my-greeter", "good"))
+
+    registry = NodeRegistry()
+    count = load_user_nodes(registry, str(tmp_path))
+
+    assert count == 1  # the good node still loads
+    assert "good" in registry.node_names()