blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/rust/src/nodes/api_call.rs

@@ -0,0 +1,93 @@
+use async_trait::async_trait;
+use std::collections::HashMap;
+
+use crate::node::NodeHandler;
+use crate::types::Context;
+
+/// 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)
+pub struct ApiCallNode;
+
+type BoxError = Box<dyn std::error::Error + Send + Sync>;
+
+#[async_trait]
+impl NodeHandler for ApiCallNode {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, BoxError> {
+        let url = config
+            .get("url")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| -> BoxError {
+                "'url' is required in node config".into()
+            })?;
+
+        let method = config
+            .get("method")
+            .and_then(|v| v.as_str())
+            .unwrap_or("GET")
+            .to_uppercase();
+
+        let timeout = config
+            .get("timeout")
+            .and_then(|v| v.as_u64())
+            .unwrap_or(10);
+
+        let client = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_secs(timeout))
+            .build()?;
+
+        let mut req_builder = match method.as_str() {
+            "POST" => client.post(url),
+            "PUT" => client.put(url),
+            "PATCH" => client.patch(url),
+            "DELETE" => client.delete(url),
+            "HEAD" => client.head(url),
+            _ => client.get(url),
+        };
+
+        // Add request body for POST/PUT/PATCH
+        if matches!(method.as_str(), "POST" | "PUT" | "PATCH") {
+            if let Some(body) = ctx.request.body.get("body") {
+                req_builder = req_builder.json(body);
+            }
+        }
+
+        // Add headers from config
+        if let Some(headers) = config.get("headers").and_then(|v| v.as_object()) {
+            for (k, v) in headers {
+                if let Some(val) = v.as_str() {
+                    req_builder = req_builder.header(k.as_str(), val);
+                }
+            }
+        }
+
+        let response: reqwest::Response = req_builder.send().await?;
+
+        let status = response.status().as_u16();
+        let resp_headers: HashMap<String, String> = response
+            .headers()
+            .iter()
+            .map(|(k, v): (&reqwest::header::HeaderName, &reqwest::header::HeaderValue)| {
+                (k.to_string(), v.to_str().unwrap_or("").to_string())
+            })
+            .collect();
+
+        let body_text: String = response.text().await?;
+
+        let data: serde_json::Value =
+            serde_json::from_str(&body_text).unwrap_or(serde_json::Value::String(body_text));
+
+        Ok(serde_json::json!({
+            "status": status,
+            "data": data,
+            "headers": resp_headers,
+        }))
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/nodes/blok_error_demo.rs

@@ -0,0 +1,151 @@
+//! Example node demonstrating the structured `BlokError` API per master plan §17.
+//!
+//! Used by the cross-language E2E test
+//! (`core/runner/__tests__/integration/runtimes/rust-grpc.integration.test.ts`)
+//! to verify that a Rust-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).
+//!
+//! Triggered via the `mode` config:
+//! - `mode="dependency"` (default) — returns `BlokError::dependency()` with a
+//!   cause chain rooted in a `std::io::Error`.
+//! - `mode="rate-limit"` — returns `BlokError::rate_limit()` with `retry_after_ms`.
+//! - `mode="validation"` — returns `BlokError::validation()` with `details.issues`.
+//! - `mode="ok"` — returns success.
+
+use async_trait::async_trait;
+use std::collections::HashMap;
+use std::time::Duration;
+
+use crate::blok_error::{build_context_snapshot, BlokError};
+use crate::node::NodeHandler;
+use crate::types::Context;
+
+pub struct BlokErrorDemoNode;
+
+#[async_trait]
+impl NodeHandler for BlokErrorDemoNode {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        let mode = config
+            .get("mode")
+            .and_then(|v| v.as_str())
+            .unwrap_or("dependency");
+
+        if mode == "ok" {
+            return Ok(serde_json::json!({"ok": true, "language": "rust"}));
+        }
+
+        let snapshot = build_context_snapshot(config, &ctx.vars);
+
+        if mode == "rate-limit" {
+            let err = 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(serde_json::json!({"limit": 5000, "remaining": 0}))
+                .context_snapshot(snapshot)
+                .build();
+            return Err(Box::new(err));
+        }
+
+        if mode == "validation" {
+            let err = 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(serde_json::json!({
+                    "issues": [
+                        {"path": ["email"], "message": "Required"},
+                        {"path": ["name"], "message": "Required"},
+                    ],
+                }))
+                .context_snapshot(snapshot)
+                .build();
+            return Err(Box::new(err));
+        }
+
+        // default: dependency with a cause chain rooted in a std::io::Error.
+        let cause = std::io::Error::new(
+            std::io::ErrorKind::ConnectionRefused,
+            "[Errno 61] Connection refused",
+        );
+        let err = 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)
+            .retry_after(Duration::from_secs(5))
+            .doc_url("https://docs.example.com/errors/POSTGRES_CONNECT_TIMEOUT")
+            .details(serde_json::json!({
+                "host": "db.internal",
+                "port": 5432,
+                "timeout_ms": 5000,
+            }))
+            .context_snapshot(snapshot)
+            .build();
+        Err(Box::new(err))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockContext;
+
+    #[tokio::test]
+    async fn ok_mode_returns_success_payload() {
+        let mut ctx = MockContext::new().build();
+        let config = HashMap::from([("mode".into(), serde_json::json!("ok"))]);
+        let result = BlokErrorDemoNode.execute(&mut ctx, &config).await.unwrap();
+        assert_eq!(result["ok"], true);
+        assert_eq!(result["language"], "rust");
+    }
+
+    #[tokio::test]
+    async fn dependency_mode_returns_typed_blok_error() {
+        let mut ctx = MockContext::new().build();
+        let config = HashMap::from([("mode".into(), serde_json::json!("dependency"))]);
+        let err = BlokErrorDemoNode.execute(&mut ctx, &config).await.unwrap_err();
+        let blok = err.downcast::<BlokError>().expect("expected BlokError");
+        assert_eq!(blok.code, "POSTGRES_CONNECT_TIMEOUT");
+        assert_eq!(blok.category.as_str(), "DEPENDENCY");
+        assert_eq!(blok.http_status, 502);
+        assert!(blok.retryable);
+        assert_eq!(blok.retry_after_ms, 5_000);
+        assert!(!blok.causes.is_empty());
+    }
+
+    #[tokio::test]
+    async fn rate_limit_mode_attaches_retry_after() {
+        let mut ctx = MockContext::new().build();
+        let config = HashMap::from([("mode".into(), serde_json::json!("rate-limit"))]);
+        let err = BlokErrorDemoNode.execute(&mut ctx, &config).await.unwrap_err();
+        let blok = err.downcast::<BlokError>().unwrap();
+        assert_eq!(blok.code, "UPSTREAM_RATE_LIMITED");
+        assert_eq!(blok.http_status, 429);
+        assert_eq!(blok.retry_after_ms, 60_000);
+    }
+
+    #[tokio::test]
+    async fn validation_mode_attaches_issues() {
+        let mut ctx = MockContext::new().build();
+        let config = HashMap::from([("mode".into(), serde_json::json!("validation"))]);
+        let err = BlokErrorDemoNode.execute(&mut ctx, &config).await.unwrap_err();
+        let blok = err.downcast::<BlokError>().unwrap();
+        assert_eq!(blok.code, "VALIDATION_FAILED");
+        assert_eq!(blok.http_status, 400);
+        let issues = blok.details.as_ref().unwrap()["issues"].as_array().unwrap();
+        assert_eq!(issues.len(), 2);
+        assert_eq!(issues[0]["path"][0], "email");
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/nodes/chain_test.rs

@@ -0,0 +1,57 @@
+use async_trait::async_trait;
+use serde_json::{json, Value};
+use std::collections::HashMap;
+
+use crate::node::NodeHandler;
+use crate::types::Context;
+
+/// 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.
+pub struct ChainTestNode;
+
+#[async_trait]
+impl NodeHandler for ChainTestNode {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, Value>,
+    ) -> Result<Value, Box<dyn std::error::Error + Send + Sync>> {
+        // 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.
+        let mut chain: Vec<Value> = config
+            .get("chain")
+            .and_then(|v| v.as_array().cloned())
+            .or_else(|| ctx.request.body.get("chain").and_then(|v| v.as_array().cloned()))
+            .unwrap_or_default();
+
+        // Read origin — same dual-read.
+        let origin = config
+            .get("origin")
+            .and_then(|v| v.as_str())
+            .or_else(|| ctx.request.body.get("origin").and_then(|v| v.as_str()))
+            .unwrap_or("unknown")
+            .to_string();
+
+        // Append this language's entry
+        let order = chain.len() + 1;
+        let entry = json!({
+            "language": "rust",
+            "order": order,
+            "timestamp": chrono::Utc::now().to_rfc3339(),
+        });
+        chain.push(entry);
+
+        // Store in context vars
+        ctx.vars
+            .insert("chain".to_string(), json!(chain));
+
+        Ok(json!({
+            "chain": chain,
+            "origin": origin,
+        }))
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/nodes/hello_world.rs

@@ -0,0 +1,83 @@
+use async_trait::async_trait;
+use std::collections::HashMap;
+
+use crate::node::NodeHandler;
+use crate::types::Context;
+
+/// HelloWorldNode greets the user with a configurable prefix.
+pub struct HelloWorldNode;
+
+#[async_trait]
+impl NodeHandler for HelloWorldNode {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        let name = ctx
+            .request
+            .body
+            .get("name")
+            .and_then(|v| v.as_str())
+            .unwrap_or("World");
+
+        let prefix = config
+            .get("prefix")
+            .and_then(|v| v.as_str())
+            .unwrap_or("Hello");
+
+        let message = format!("{}, {}!", prefix, name);
+
+        ctx.set_var("greeting", serde_json::Value::String(message.clone()));
+
+        Ok(serde_json::json!({
+            "message": message,
+            "timestamp": chrono::Utc::now().to_rfc3339(),
+            "language": "rust"
+        }))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockContext;
+
+    #[tokio::test]
+    async fn test_hello_world_default() {
+        let node = HelloWorldNode;
+        let mut ctx = MockContext::new().build();
+        let result = node.execute(&mut ctx, &HashMap::new()).await.unwrap();
+        assert_eq!(result["message"], "Hello, World!");
+        assert_eq!(result["language"], "rust");
+    }
+
+    #[tokio::test]
+    async fn test_hello_world_with_name() {
+        let node = HelloWorldNode;
+        let mut ctx = MockContext::new()
+            .with_body(serde_json::json!({"name": "Blok"}))
+            .build();
+        let result = node.execute(&mut ctx, &HashMap::new()).await.unwrap();
+        assert_eq!(result["message"], "Hello, Blok!");
+    }
+
+    #[tokio::test]
+    async fn test_hello_world_with_prefix() {
+        let node = HelloWorldNode;
+        let mut ctx = MockContext::new()
+            .with_body(serde_json::json!({"name": "World"}))
+            .build();
+        let config = HashMap::from([("prefix".into(), serde_json::json!("Hi"))]);
+        let result = node.execute(&mut ctx, &config).await.unwrap();
+        assert_eq!(result["message"], "Hi, World!");
+    }
+
+    #[tokio::test]
+    async fn test_hello_world_sets_var() {
+        let node = HelloWorldNode;
+        let mut ctx = MockContext::new().build();
+        node.execute(&mut ctx, &HashMap::new()).await.unwrap();
+        assert!(ctx.get_var_str("greeting").is_some());
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/nodes/mod.rs

@@ -0,0 +1,18 @@
+pub mod api_call;
+pub mod blok_error_demo;
+pub mod chain_test;
+pub mod hello_world;
+pub mod transform_data;
+pub mod typed_greet;
+
+use crate::registry::NodeRegistry;
+
+/// Register all example nodes with the registry.
+pub fn register_all(registry: &mut NodeRegistry) {
+    registry.register("hello-world", hello_world::HelloWorldNode);
+    registry.register("api-call", api_call::ApiCallNode);
+    registry.register("transform-data", transform_data::TransformDataNode);
+    registry.register("chain-test", chain_test::ChainTestNode);
+    registry.register("blok-error-demo", blok_error_demo::BlokErrorDemoNode);
+    registry.register_typed(typed_greet::TypedGreetNode);
+}

package/dist/scaffold-repo/sdks/rust/src/nodes/transform_data.rs

@@ -0,0 +1,142 @@
+use async_trait::async_trait;
+use std::collections::HashMap;
+
+use crate::errors::NodeError;
+use crate::node::NodeHandler;
+use crate::types::Context;
+
+/// TransformDataNode transforms JSON data based on field mappings.
+///
+/// Config:
+///   - `mappings` (object): Map of target field name → source field path (dot-notation)
+///   - `include_only` (array, optional): Only include these fields
+///   - `exclude` (array, optional): Exclude these fields
+///   - `defaults` (object, optional): Default values for missing fields
+pub struct TransformDataNode;
+
+#[async_trait]
+impl NodeHandler for TransformDataNode {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        let body = ctx
+            .request
+            .body
+            .as_object()
+            .ok_or_else(|| NodeError::validation("request body must be a JSON object"))?;
+
+        let mut result = serde_json::Map::new();
+
+        // Apply field mappings if configured
+        if let Some(mappings) = config.get("mappings").and_then(|v| v.as_object()) {
+            for (target, source_path) in mappings {
+                if let Some(source) = source_path.as_str() {
+                    if let Some(value) = get_nested_value(&ctx.request.body, source) {
+                        result.insert(target.clone(), value.clone());
+                    }
+                }
+            }
+        } else {
+            // No mappings — copy all fields
+            for (k, v) in body {
+                result.insert(k.clone(), v.clone());
+            }
+        }
+
+        // Apply include_only filter
+        if let Some(include_only) = config.get("include_only").and_then(|v| v.as_array()) {
+            let allowed: Vec<&str> = include_only.iter().filter_map(|v| v.as_str()).collect();
+            result.retain(|k, _| allowed.contains(&k.as_str()));
+        }
+
+        // Apply exclude filter
+        if let Some(exclude) = config.get("exclude").and_then(|v| v.as_array()) {
+            for field in exclude.iter().filter_map(|v| v.as_str()) {
+                result.remove(field);
+            }
+        }
+
+        // Apply defaults
+        if let Some(defaults) = config.get("defaults").and_then(|v| v.as_object()) {
+            for (k, v) in defaults {
+                if !result.contains_key(k) {
+                    result.insert(k.clone(), v.clone());
+                }
+            }
+        }
+
+        let output = serde_json::Value::Object(result);
+        ctx.set_var("transformed_data", output.clone());
+
+        Ok(output)
+    }
+}
+
+fn get_nested_value<'a>(data: &'a serde_json::Value, path: &str) -> Option<&'a serde_json::Value> {
+    let mut current = data;
+    for part in path.split('.') {
+        current = current.get(part)?;
+    }
+    Some(current)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockContext;
+
+    #[tokio::test]
+    async fn test_transform_copy_all() {
+        let node = TransformDataNode;
+        let mut ctx = MockContext::new()
+            .with_body(serde_json::json!({"name": "John", "age": 30}))
+            .build();
+        let result = node.execute(&mut ctx, &HashMap::new()).await.unwrap();
+        assert_eq!(result["name"], "John");
+        assert_eq!(result["age"], 30);
+    }
+
+    #[tokio::test]
+    async fn test_transform_with_mappings() {
+        let node = TransformDataNode;
+        let mut ctx = MockContext::new()
+            .with_body(serde_json::json!({"first_name": "John", "last_name": "Doe"}))
+            .build();
+        let config = HashMap::from([(
+            "mappings".into(),
+            serde_json::json!({"full_name": "first_name", "surname": "last_name"}),
+        )]);
+        let result = node.execute(&mut ctx, &config).await.unwrap();
+        assert_eq!(result["full_name"], "John");
+        assert_eq!(result["surname"], "Doe");
+    }
+
+    #[tokio::test]
+    async fn test_transform_with_exclude() {
+        let node = TransformDataNode;
+        let mut ctx = MockContext::new()
+            .with_body(serde_json::json!({"name": "John", "secret": "hidden", "age": 30}))
+            .build();
+        let config = HashMap::from([("exclude".into(), serde_json::json!(["secret"]))]);
+        let result = node.execute(&mut ctx, &config).await.unwrap();
+        assert!(result.get("secret").is_none());
+        assert_eq!(result["name"], "John");
+    }
+
+    #[tokio::test]
+    async fn test_transform_with_defaults() {
+        let node = TransformDataNode;
+        let mut ctx = MockContext::new()
+            .with_body(serde_json::json!({"name": "John"}))
+            .build();
+        let config = HashMap::from([(
+            "defaults".into(),
+            serde_json::json!({"role": "user", "active": true}),
+        )]);
+        let result = node.execute(&mut ctx, &config).await.unwrap();
+        assert_eq!(result["role"], "user");
+        assert_eq!(result["active"], true);
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/nodes/typed_greet.rs

@@ -0,0 +1,56 @@
+use async_trait::async_trait;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::blok_error::BlokError;
+use crate::node::TypedNode;
+use crate::types::Context;
+
+fn default_repeat() -> u32 {
+    1
+}
+
+/// Validated input for the typed-greet demo (SPEC-B contract).
+#[derive(Deserialize, JsonSchema)]
+pub struct TypedGreetInput {
+    pub name: String,
+    #[serde(default = "default_repeat")]
+    pub repeat: u32,
+}
+
+/// Typed output for the typed-greet demo.
+#[derive(Serialize, JsonSchema)]
+pub struct TypedGreetOutput {
+    pub greeting: String,
+    pub length: usize,
+}
+
+/// Typed greeting node built with the `TypedNode` contract (SPEC-B P3).
+pub struct TypedGreetNode;
+
+#[async_trait]
+impl TypedNode for TypedGreetNode {
+    type Input = TypedGreetInput;
+    type Output = TypedGreetOutput;
+
+    fn name(&self) -> &str {
+        "typed-greet"
+    }
+
+    fn description(&self) -> &str {
+        "Typed greeting (SPEC-B contract demo)"
+    }
+
+    async fn run(
+        &self,
+        _ctx: &mut Context,
+        input: TypedGreetInput,
+    ) -> Result<TypedGreetOutput, BlokError> {
+        let repeat = input.repeat.max(1) as usize;
+        let greeting = format!("Hello, {}", input.name).repeat(repeat);
+        Ok(TypedGreetOutput {
+            length: greeting.len(),
+            greeting,
+        })
+    }
+}