blokctl 0.6.21 → 1.0.0

package/dist/commands/create/utils/Examples.js

@@ -32,36 +32,27 @@ const package_dev_dependencies = {
     "@types/ejs": "^3.1.5",
     "@types/pg": "^8.11.11",
 };
-const python3_file = `
-from core.blok import BlokService
-from core.types.context import Context
-from core.types.blok_response import BlokResponse
-from core.types.global_error import GlobalError
-from typing import Any, Dict
-import traceback
-
-class Node(BlokService):
-    def __init__(self):
-        BlokService.__init__(self)
-        self.input_schema = {}
-        self.output_schema = {}
-
-    async def handle(self, ctx: Context, inputs: Dict[str, Any]) -> BlokResponse:
-        response = BlokResponse()
-
-        try:
-            response.setSuccess({ "message": "Hello World from Python3!" })
-        except Exception as error:
-            err = GlobalError(error)
-            err.setCode(500)
-            err.setName(self.name)
-
-            stack_trace = traceback.format_exc()
-            err.setStack(stack_trace)
-            response.success = False
-            response.setError(err)
-
-        return response
+const python3_file = `from pydantic import BaseModel
+
+from blok import node
+from blok.types.context import Context
+
+
+class Input(BaseModel):
+    """Validated inputs for the {{NODE_NAME}} node."""
+
+    name: str = "world"
+
+
+class Output(BaseModel):
+    message: str
+
+
+@node("{{NODE_NAME}}", "Describe what {{NODE_NAME}} does")
+def run(ctx: Context, input: Input) -> Output:
+    # \`input\` is already validated against Input; the return is validated
+    # against Output and serialized for you.
+    return Output(message=f"Hello, {input.name}!")
 `;
 const examples_url = `
 Examples:
@@ -121,316 +112,151 @@ autorestart=true
 stderr_logfile=/var/log/python.err.log
 stdout_logfile=/var/log/python.out.log
 `;
-const go_node_file = `package main
+const go_node_file = `// {{NODE_NAME}} — a Blok node for the Go runtime.
+package {{NODE_PKG}}
 
 import (
-	"github.com/blok/sdk"
+	blok "github.com/nickincloud/blok-go"
 )
 
-type HelloWorldNode struct{}
+// {{NODE_NAME_PASCAL}}Node implements blok.NodeHandler.
+type {{NODE_NAME_PASCAL}}Node struct{}
 
-func (n *HelloWorldNode) Execute(ctx *sdk.Context, config map[string]interface{}) (*sdk.ExecutionResult, error) {
-	// Access request body
+// Execute runs the node. Input arrives on ctx.Request; config holds the step's
+// inputs from the workflow. Return any JSON-serialisable value (or an error).
+func (n *{{NODE_NAME_PASCAL}}Node) Execute(ctx *blok.Context, config map[string]interface{}) (interface{}, error) {
 	name := "World"
-	if body, ok := ctx.Request.Body.(map[string]interface{}); ok {
-		if nameVal, ok := body["name"].(string); ok {
-			name = nameVal
+	if body := ctx.Request.BodyMap(); body != nil {
+		if v, ok := body["name"].(string); ok {
+			name = v
 		}
 	}
 
-	// Access configuration
 	prefix := "Hello"
-	if prefixVal, ok := config["prefix"].(string); ok {
-		prefix = prefixVal
+	if v, ok := config["prefix"].(string); ok {
+		prefix = v
 	}
 
-	// Store result in context for downstream nodes
-	ctx.Vars["greeting"] = prefix + ", " + name + "!"
-
-	// Return successful result
-	return &sdk.ExecutionResult{
-		Success: true,
-		Data: map[string]interface{}{
-			"message": prefix + ", " + name + "!",
-			"timestamp": sdk.GetCurrentTimestamp(),
-			"language": "Go",
-		},
-		Errors: nil,
+	return map[string]interface{}{
+		"message":  prefix + ", " + name + "!",
+		"language": "Go",
 	}, nil
 }
 
-func main() {
-	// Register node
-	registry := sdk.NewNodeRegistry()
-	registry.Register("{{NODE_NAME}}", &HelloWorldNode{})
-
-	// Start HTTP server
-	server := sdk.NewHTTPServer(registry, ":8080")
-	if err := server.Start(); err != nil {
-		panic(err)
-	}
+// Register wires this node into the runtime registry. The generated
+// register_user_nodes.go calls it for every node under runtimes/go/nodes.
+func Register(registry *blok.NodeRegistry) {
+	registry.Register("{{NODE_NAME}}", &{{NODE_NAME_PASCAL}}Node{})
 }
 `;
-const go_mod_file = `module github.com/blok/nodes/{{NODE_NAME}}
-
-go 1.21
-
-require github.com/blok/sdk v1.0.0
-`;
-const go_dockerfile = `FROM golang:1.21-alpine AS builder
+const java_node_file = `package com.blok.blok.nodes;
 
-WORKDIR /app
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -o /node main.go
-
-FROM alpine:latest
-RUN apk --no-cache add ca-certificates
-WORKDIR /root/
-COPY --from=builder /node .
-
-EXPOSE 8080
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\
-  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
-
-CMD ["./node"]
-`;
-const java_node_file = `package com.blok.nodes;
+import com.blok.blok.node.NodeHandler;
+import com.blok.blok.types.Context;
 
-import com.blok.runtime.Blok;
-import com.blok.runtime.NodeRegistry;
-import com.blok.server.RuntimeServer;
+import java.time.Instant;
 import java.util.HashMap;
 import java.util.Map;
 
-public class HelloWorldNode implements Blok.NodeHandler {
+/**
+ * {{NODE_NAME}} — a Blok node for the Java runtime.
+ *
+ * <p>Input arrives on {@code ctx.getRequest().bodyMap()} (a Map, or null when
+ * the body isn't an object); {@code config} holds the step's inputs from the
+ * workflow. Return any JSON-serialisable value (a Map here), or throw to fail
+ * the step. {@code blokctl dev} discovers this class under
+ * {@code runtimes/java/nodes/} and registers it into the Java runtime.
+ */
+public class {{NODE_NAME_PASCAL}}Node implements NodeHandler {
+
     @Override
-    public Blok.ExecutionResult execute(Blok.Context ctx, Map<String, Object> config) {
-        try {
-            // Access request body
-            String name = "World";
-            if (ctx.request.body != null && ctx.request.body.containsKey("name")) {
-                name = (String) ctx.request.body.get("name");
-            }
-
-            // Access configuration
-            String prefix = "Hello";
-            if (config != null && config.containsKey("prefix")) {
-                prefix = (String) config.get("prefix");
-            }
-
-            // Store result in context for downstream nodes
-            String greeting = prefix + ", " + name + "!";
-            ctx.vars.put("greeting", greeting);
-
-            // Build response data
-            Map<String, Object> data = new HashMap<>();
-            data.put("message", greeting);
-            data.put("timestamp", System.currentTimeMillis());
-            data.put("language", "Java");
-
-            // Return successful result
-            return new Blok.ExecutionResult(true, data, null, null, null);
-        } catch (Exception e) {
-            return new Blok.ExecutionResult(false, null, e.getMessage(), null, null);
+    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 && !s.isEmpty()) {
+            name = s;
         }
-    }
 
-    public static void main(String[] args) {
-        try {
-            // Register node
-            NodeRegistry registry = new NodeRegistry();
-            registry.register("{{NODE_NAME}}", new HelloWorldNode());
-
-            // Start HTTP server
-            RuntimeServer server = new RuntimeServer(registry, 8080);
-            server.start();
-        } catch (Exception e) {
-            e.printStackTrace();
-            System.exit(1);
+        String prefix = "Hello";
+        if (config != null && config.get("prefix") instanceof String s && !s.isEmpty()) {
+            prefix = s;
         }
-    }
-}
-`;
-const java_pom_file = `<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
-         http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
-
-    <groupId>com.blok</groupId>
-    <artifactId>{{NODE_NAME}}</artifactId>
-    <version>1.0.0</version>
-
-    <properties>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    </properties>
-
-    <dependencies>
-        <dependency>
-            <groupId>com.google.code.gson</groupId>
-            <artifactId>gson</artifactId>
-            <version>2.10.1</version>
-        </dependency>
-    </dependencies>
-
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-shade-plugin</artifactId>
-                <version>3.5.0</version>
-                <executions>
-                    <execution>
-                        <phase>package</phase>
-                        <goals>
-                            <goal>shade</goal>
-                        </goals>
-                        <configuration>
-                            <transformers>
-                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
-                                    <mainClass>com.blok.nodes.HelloWorldNode</mainClass>
-                                </transformer>
-                            </transformers>
-                        </configuration>
-                    </execution>
-                </executions>
-            </plugin>
-        </plugins>
-    </build>
-</project>
-`;
-const java_dockerfile = `FROM maven:3.9-eclipse-temurin-17 AS builder
-
-WORKDIR /app
-COPY pom.xml .
-RUN mvn dependency:go-offline
-
-COPY src ./src
-RUN mvn clean package -DskipTests
-
-FROM eclipse-temurin:17-jre-alpine
 
-WORKDIR /root/
-COPY --from=builder /app/target/{{NODE_NAME}}-1.0.0.jar ./app.jar
+        String message = prefix + ", " + name + "!";
 
-EXPOSE 8080
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\
-  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
+        // Publish a value for downstream nodes via context vars.
+        ctx.setVar("greeting", message);
 
-CMD ["java", "-jar", "app.jar"]
+        Map<String, Object> result = new HashMap<>();
+        result.put("message", message);
+        result.put("timestamp", Instant.now().toString());
+        result.put("language", "Java");
+        return result;
+    }
+}
 `;
 const rust_node_file = `use async_trait::async_trait;
-use blok::{NodeHandler, NodeRegistry, Context};
+use blok::registry::NodeRegistry;
+use blok::{Context, NodeHandler};
 use std::collections::HashMap;
 
-/// {{NODE_NAME}} - A Blok node implemented in Rust
-struct {{NODE_NAME_PASCAL}};
+/// {{NODE_NAME_PASCAL}}Node implements blok::NodeHandler.
+struct {{NODE_NAME_PASCAL}}Node;
 
 #[async_trait]
-impl NodeHandler for {{NODE_NAME_PASCAL}} {
+impl NodeHandler for {{NODE_NAME_PASCAL}}Node {
+    /// Execute runs the node. Input arrives on ctx.request; config holds the
+    /// step's inputs from the workflow. Return any JSON value (or an error).
     async fn execute(
         &self,
         ctx: &mut Context,
         config: &HashMap<String, serde_json::Value>,
     ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
-        // Access request body
-        let name = ctx.request.body
+        let name = ctx
+            .request
+            .body
             .get("name")
             .and_then(|v| v.as_str())
             .unwrap_or("World");
 
-        // Access configuration
         let prefix = config
             .get("prefix")
             .and_then(|v| v.as_str())
             .unwrap_or("Hello");
 
-        let message = format!("{}, {}!", prefix, name);
-
-        // Store in context vars for downstream nodes
-        ctx.vars.insert(
-            "greeting".to_string(),
-            serde_json::Value::String(message.clone()),
-        );
-
-        // Return response
         Ok(serde_json::json!({
-            "message": message,
+            "message": format!("{}, {}!", prefix, name),
             "language": "Rust"
         }))
     }
 }
 
-#[tokio::main]
-async fn main() {
-    // Initialize tracing
-    tracing_subscriber::fmt::init();
-
-    // Register nodes
-    let mut registry = NodeRegistry::new("1.0.0");
-    registry.register("{{NODE_NAME}}", {{NODE_NAME_PASCAL}});
-
-    // Start HTTP server
-    blok::server::serve(registry, 8080).await.unwrap();
+/// register wires this node into the runtime registry. The generated
+/// user_nodes/mod.rs calls it for every node under runtimes/rust/nodes.
+pub fn register(registry: &mut NodeRegistry) {
+    registry.register("{{NODE_NAME}}", {{NODE_NAME_PASCAL}}Node);
 }
 `;
-const rust_cargo_file = `[package]
-name = "{{NODE_NAME}}"
-version = "1.0.0"
-edition = "2021"
-
-[[bin]]
-name = "{{NODE_NAME}}"
-path = "src/main.rs"
-
-[dependencies]
-blok = { path = "../../sdk" }
-tokio = { version = "1", features = ["full"] }
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
-async-trait = "0.1"
-tracing = "0.1"
-tracing-subscriber = "0.3"
-`;
-const rust_dockerfile = `FROM rust:1.77-alpine AS builder
-
-RUN apk add --no-cache musl-dev
-
-WORKDIR /app
-COPY Cargo.toml Cargo.lock ./
-RUN mkdir -p src && echo 'fn main() {}' > src/main.rs && \\
-    cargo build --release 2>/dev/null || true && rm -rf src
-
-COPY . .
-RUN cargo build --release
-
-FROM alpine:latest
-RUN apk --no-cache add ca-certificates
-WORKDIR /root/
-COPY --from=builder /app/target/release/{{NODE_NAME}} .
-
-EXPOSE 8080
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\
-  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
-
-CMD ["./{{NODE_NAME}}"]
-`;
 const csharp_node_file = `using System.Text.Json;
-using Blok.Runtime;
+using Blok.Core.Node;
+using Blok.Core.Types;
 
-namespace Blok.Runtime.Nodes;
+namespace Blok.Core.Nodes;
 
+/// <summary>
+/// {{NODE_NAME_PASCAL}}Node — a Blok node for the C# runtime. Discovered under
+/// runtimes/csharp/nodes/ and registered into the shared gRPC server alongside
+/// the built-in nodes (same model as the other SDKs). Run \`blokctl dev\`; no
+/// per-node csproj/Dockerfile — it isn't a standalone service.
+/// </summary>
 public class {{NODE_NAME_PASCAL}}Node : INodeHandler
 {
+    /// <summary>
+    /// Execute the node. Input arrives on ctx.Request; config holds the step's
+    /// inputs from the workflow. Return any JSON-serialisable value.
+    /// </summary>
     public Task<JsonElement> ExecuteAsync(Context ctx, Dictionary<string, JsonElement> config)
     {
-        // Access request body
         var name = "World";
         if (ctx.Request.Body.ValueKind == JsonValueKind.Object &&
             ctx.Request.Body.TryGetProperty("name", out var nameEl) &&
@@ -439,7 +265,6 @@ public class {{NODE_NAME_PASCAL}}Node : INodeHandler
             name = nameEl.GetString() ?? "World";
         }
 
-        // Access configuration
         var prefix = "Hello";
         if (config.TryGetValue("prefix", out var prefixEl) &&
             prefixEl.ValueKind == JsonValueKind.String)
@@ -448,11 +273,8 @@ public class {{NODE_NAME_PASCAL}}Node : INodeHandler
         }
 
         var message = $"{prefix}, {name}!";
+        ctx.SetVar("greeting", message);
 
-        // Store in context for downstream nodes
-        ctx.Vars["greeting"] = JsonSerializer.SerializeToElement(message);
-
-        // Return response
         var result = JsonSerializer.SerializeToElement(new
         {
             message,
@@ -464,154 +286,58 @@ public class {{NODE_NAME_PASCAL}}Node : INodeHandler
     }
 }
 `;
-const csharp_csproj_file = `<Project Sdk="Microsoft.NET.Sdk.Web">
-  <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <RootNamespace>Blok.Runtime</RootNamespace>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-  </PropertyGroup>
-</Project>
-`;
-const csharp_dockerfile = `FROM mcr.microsoft.com/dotnet/sdk:8.0 AS builder
-WORKDIR /app
-COPY *.csproj .
-RUN dotnet restore
-COPY . .
-RUN dotnet publish -c Release -o /out
-
-FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine
-WORKDIR /app
-COPY --from=builder /out .
-
-EXPOSE 8080
-ENV PORT=8080
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\
-  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
-
-CMD ["dotnet", "BlokRuntime.dll"]
-`;
 const php_node_file = `<?php
 
-namespace Blok\\Nodes;
+declare(strict_types=1);
 
-use Blok\\NodeHandler;
-use Blok\\Context;
+namespace Blok\\Blok\\Nodes\\{{NODE_NAME_PASCAL}};
 
-class {{NODE_NAME_PASCAL}}Node implements NodeHandler
+use Blok\\Blok\\Node\\NodeHandler;
+use Blok\\Blok\\Types\\Context;
+
+/**
+ * {{NODE_NAME}} — a Blok node for the PHP runtime.
+ *
+ * Input arrives on \$ctx->request; \$config holds the step's inputs from the
+ * workflow. Return any JSON-serialisable value (array, scalar, etc.).
+ */
+final class {{NODE_NAME_PASCAL}}Node implements NodeHandler
 {
     public function execute(Context $ctx, array $config): mixed
     {
-        // Access request body
-        $name = $ctx->request->body['name'] ?? 'World';
-
-        // Access configuration
-        $prefix = $config['prefix'] ?? 'Hello';
-
-        $message = "$prefix, $name!";
+        $name = $ctx->request->bodyStr('name') ?? 'World';
+        $prefix = isset($config['prefix']) && is_string($config['prefix'])
+            ? $config['prefix']
+            : 'Hello';
 
-        // Store in context for downstream nodes
-        $ctx->vars['greeting'] = $message;
-
-        // Return response
         return [
-            'message' => $message,
-            'timestamp' => date('c'),
+            'message' => sprintf('%s, %s!', $prefix, $name),
             'language' => 'PHP',
         ];
     }
 }
 `;
-const php_composer_file = `{
-    "name": "blok/{{NODE_NAME}}",
-    "type": "project",
-    "require": {
-        "php": ">=8.2",
-        "react/http": "^1.9",
-        "react/socket": "^1.15"
-    },
-    "autoload": {
-        "psr-4": {
-            "Blok\\\\": "src/"
-        }
-    }
-}
-`;
-const php_dockerfile = `FROM php:8.2-cli-alpine AS builder
-WORKDIR /app
-COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
-COPY composer.json .
-RUN composer install --no-dev --optimize-autoloader
-COPY . .
-
-FROM php:8.2-cli-alpine
-WORKDIR /app
-COPY --from=builder /app .
-
-EXPOSE 8080
-ENV PORT=8080
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\
-  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
-
-CMD ["php", "index.php"]
-`;
-const ruby_node_file = `require_relative '../../lib/blok'
-
-module Blok
-  module Nodes
-    class {{NODE_NAME_PASCAL}}Node < Blok::NodeHandler
-      def execute(ctx, config)
-        # Access request body
-        name = ctx.request.body.is_a?(Hash) ? ctx.request.body['name'] : nil
-        name ||= 'World'
+const ruby_node_file = `# frozen_string_literal: true
 
-        # Access configuration
-        prefix = config['prefix'] || 'Hello'
+# {{NODE_NAME_PASCAL}}Node — registered as "{{NODE_NAME}}" by the Ruby runtime.
+#
+# Request body arrives on ctx.request (use body_str(key) for a String|nil);
+# config holds the step's inputs from the workflow. Return any
+# JSON-serialisable Hash. Publish to downstream steps with ctx.set_var(k, v).
+class {{NODE_NAME_PASCAL}}Node < Blok::Node::NodeHandler
+  def execute(ctx, config)
+    name   = ctx.request.body_str("name") || "World"
+    prefix = config["prefix"] || "Hello"
 
-        message = "#{prefix}, #{name}!"
+    message = "#{prefix}, #{name}!"
+    ctx.set_var("greeting", message)
 
-        # Store in context for downstream nodes
-        ctx.vars['greeting'] = message
-
-        # Return response
-        {
-          'message' => message,
-          'timestamp' => Time.now.utc.iso8601,
-          'language' => 'Ruby'
-        }
-      end
-    end
+    {
+      "message"  => message,
+      "language" => "Ruby"
+    }
   end
-end
-`;
-const ruby_gemfile = `source 'https://rubygems.org'
-
-ruby '>= 3.1'
-
-gem 'sinatra', '~> 4.0'
-gem 'puma', '~> 6.4'
-gem 'rackup', '~> 2.1'
-`;
-const ruby_dockerfile = `FROM ruby:3.2-alpine AS builder
-RUN apk add --no-cache build-base
-WORKDIR /app
-COPY Gemfile Gemfile.lock ./
-RUN bundle install --without development test
-
-FROM ruby:3.2-alpine
-RUN apk --no-cache add ca-certificates wget
-WORKDIR /app
-COPY --from=builder /usr/local/bundle /usr/local/bundle
-COPY . .
-
-EXPOSE 8080
-ENV PORT=8080
-ENV RACK_ENV=production
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\
-  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
-
-CMD ["bundle", "exec", "puma", "-b", "tcp://0.0.0.0:8080"]
-`;
+end`;
 const agents_md = `
 # AGENTS.md — Blok Framework AI Context
 
@@ -623,7 +349,52 @@ Blok is a **multi-trigger, multi-runtime workflow framework**. A workflow is a d
 The 9 trigger types: \`http\`, \`worker\`, \`cron\`, \`pubsub\`, \`sse\`, \`websocket\`, \`webhook\`, \`mcp\`, \`grpc\`.
 The 8 runtimes: \`typescript\` (in-process), \`go\`, \`rust\`, \`java\`, \`csharp\`, \`php\`, \`ruby\`, \`python3\`.
 
-The canonical workflow form is \`workflow({ name, version, trigger, steps })\` from \`@blokjs/helper\`. The same shape works for all 9 triggers — only the \`trigger:\` block changes.
+The canonical TypeScript form is the **typed-handle DSL** from \`@blokjs/core\`: \`workflow(name, { version, trigger }, (entry) => { ... })\`, where each \`step()\` returns a typed handle you reference directly — **no \`$\`, no \`js/\`, no raw \`ctx\` strings.** The object-style \`workflow({ name, version, trigger, steps: [...] })\` from \`@blokjs/helper\` and JSON workflows are equivalent (all three compile to the same IR) and remain fully supported. The same shape works for all 9 triggers — only the \`trigger:\` block changes.
+
+---
+
+## 0. THE TYPED-HANDLE DSL (\`@blokjs/core\`) — preferred for TypeScript
+
+\`\`\`ts
+import { workflow, step, branch, forEach, switchOn, tryCatch, http, tpl, gt } from "@blokjs/core";
+
+export default workflow("order-intake", { version: "1.0.0", trigger: http.post("/orders") }, (req) => {
+  // step(id, node, inputs) → a TYPED handle shaped like the node's output.
+  const order = step("validate", validateOrder, { qty: req.body.qty });
+
+  // Reference a handle field anywhere downstream — it records a ref the runner resolves.
+  step("summary", summarize, { line: tpl\`order of \${order.qty} item(s)\` });
+
+  // Control flow: a comparator (gt/eq/lt/...) builds the condition; arms are callbacks.
+  branch("lane", gt(order.qty, 10), {
+    then: () => { step("bulk", routeOrder, { lane: "bulk" }); },
+    else: () => { step("standard", routeOrder, { lane: "standard" }); },
+  });
+});
+\`\`\`
+
+**Trigger config:** \`http.{get,post,put,delete,patch,any}(path?, opts?)\` for HTTP (omit \`path\` for file-based routing). For any other trigger pass the raw block as \`trigger:\` — e.g. \`{ worker: { queue: "jobs" } }\`, \`{ cron: { schedule: "0 2 * * *" } }\`, \`{ webhook: { source: "stripe" } }\`.
+
+**The entry handle** (the callback's argument) is the trigger payload — typed and conventionally named per trigger: \`http\`→\`req\`, \`webhook\`→\`event\`, \`cron\`→\`tick\`, \`worker\`→\`job\`, \`pubsub\`→\`msg\`, \`grpc\`→\`rpc\` (others get a loose handle). Read \`req.body\`, \`req.params.id\`, \`req.query.q\`, \`req.headers["x-…"]\`.
+
+**Handles & persistence:**
+- \`const h = step("id", node, inputs)\` — every step auto-persists to \`ctx.state["id"]\` on success; \`h\` / \`h.field\` is how you reference it later (never \`$.state.id\`).
+- 4th arg \`opts\`: \`{ as: "name" }\` roots the handle at \`state["name"]\`; \`{ spread: true }\` flattens \`result.data\` into state (mutually exclusive with \`as\`); \`{ ephemeral: true }\` skips persistence (handle then unreadable downstream); also \`idempotencyKey\`, \`retry\`, \`maxDuration\`, \`type: "runtime.<lang>"\`.
+- \`tpl\`…\${h.field}…\`\` builds a string with embedded handle refs.
+- Comparators (typed): \`eq, ne, gt, gte, lt, lte, not\`. A bare boolean handle is a truthiness check.
+- \`defineNode\` is re-exported from \`@blokjs/core\` — author nodes exactly as before; just RETURN output (never write \`ctx.state\`/\`ctx.vars\`).
+
+**Control-flow primitives** (all from \`@blokjs/core\`):
+- \`branch(id, cond, { then: () => {…}, else?: () => {…} })\` — \`cond\` is a comparator or a boolean handle.
+- \`forEach(iterable, (item, index) => { step(…) }, { as?, mode?, concurrency? })\` — \`iterable\` is a handle; \`item\`/\`index\` are per-iteration handles; \`mode: "parallel"\` bounds with \`concurrency\` (default 10).
+- \`switchOn(discriminant, { cases: [{ when: "push", do: () => {…} }], default?: () => {…} }, { id })\` — \`when\` labels are STATIC literals (a handle never matches).
+- \`tryCatch(id, { try: () => {…}, catch: (error) => { step("log", logger, { msg: error.message }); }, finally?: () => {…} })\` — \`error\` is a typed handle (\`.message\`/\`.name\`/\`.stack\`/\`.code\`/\`.stepId\`).
+
+**The four footguns** (full detail: \`docs/d/primitives/handles-and-footguns.mdx\`):
+1. **Arm-scoped handles don't escape their arm.** A handle minted inside a \`branch\`/\`switchOn\`/\`tryCatch\`/\`forEach\` arm is unreadable outside it. Return a value from the control-flow step, or have both arms write one \`as:\` key.
+2. **Ephemeral handles are unreadable.** Reading an \`{ ephemeral: true }\` step's handle resolves to \`undefined\`.
+3. **Never reuse a step \`id\`** — including across mutually-exclusive arms. Ids are a flat per-workflow map; the runner throws at load time. Use \`as:\` when two arms must write the same downstream key.
+4. **Never name a \`forEach\` \`as:\`/\`asIndex\` after an existing step id** (or another loop's \`as\`) — they share \`ctx.state\`; the runner throws at load time.
 
 ---
 
@@ -1132,7 +903,7 @@ Process-global middleware: \`WorkflowRegistry.getInstance().setGlobalMiddleware(
 Always \`export default defineNode(...)\`. Never class-based \`BlokService\`. Zod input/output are mandatory.
 
 \`\`\`ts
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 import { z } from "zod";
 
 export default defineNode({
@@ -1608,7 +1379,7 @@ Per-step reliability lives on the step: \`idempotencyKey\` (cache by \`(workflow
 Always \`export default defineNode(...)\` (TS) — never class-based \`BlokService\`. Zod input/output are mandatory. Never write \`ctx.state\` from a node — return your output and let the runner persist it (use \`ctx.publish(name, value)\` for a true side-channel). No \`any\` types — use \`z.unknown()\`.
 
 \`\`\`typescript
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 import { z } from "zod";
 
 export default defineNode({
@@ -1662,7 +1433,21 @@ Registration is **manual** in non-TS runtimes — importing the module runs the
 
 ## 4. Generating Workflows
 
-Canonical form: \`workflow({ name, version, trigger, steps })\` from \`@blokjs/helper\` — one object literal, no chained builder, no separate \`nodes{}\` map. \`name\` ≥ 3 chars, \`version\` ≥ 5 chars (semver). Reference earlier outputs with \`$.state.<id>\` / \`$.req.body\`. Use \`branch\`, \`switchOn\`, \`forEach\`, \`loop\`, \`tryCatch\` (all from \`@blokjs/helper\`) for control flow.
+**Preferred (TypeScript): the typed-handle DSL from \`@blokjs/core\`.** \`workflow(name, { version, trigger }, (entry) => { ... })\` — each \`step(id, node, inputs)\` returns a typed handle you reference directly; no \`$\`, no \`js/\`, no raw \`ctx\` strings. \`http.{get,post,…}(path?)\` builds the trigger; other triggers pass the raw block (\`{ worker: { queue } }\`, \`{ cron: { schedule } }\`, …). Entry name per trigger: \`http\`→\`req\`, \`worker\`→\`job\`, \`cron\`→\`tick\`, \`webhook\`→\`event\`, \`pubsub\`→\`msg\`, \`grpc\`→\`rpc\`.
+
+\`\`\`typescript
+import { workflow, step, branch, gt, http } from "@blokjs/core";
+
+export default workflow("Process Order", { version: "1.0.0", trigger: http.post("/orders") }, (req) => {
+  const order = step("validate", orderValidator, { order: req.body });   // typed handle
+  step("save", orderStore, { data: order });                            // reference it directly
+  branch("big", gt(order.total, 100), { then: () => { step("vip", flagVip, { id: order.id }); } });
+});
+\`\`\`
+
+Control flow (all from \`@blokjs/core\`): \`branch(id, cond, {then,else?})\`, \`forEach(iterable, (item,i)=>{}, {as?,mode?})\`, \`switchOn(disc, {cases:[{when,do}],default?}, {id})\`, \`tryCatch(id, {try,catch:(err)=>{},finally?})\`; comparators \`eq/ne/gt/gte/lt/lte/not\`; \`tpl\`…\${h.x}…\`\` for strings. The **four footguns**: arm-scoped handles don't escape their arm; ephemeral handles read \`undefined\`; never reuse a step \`id\`; never name a \`forEach\` \`as:\` after an existing id. See \`docs/d/primitives/handles-and-footguns.mdx\`.
+
+**Equivalent object-style form** (\`@blokjs/helper\`, also valid; JSON mirrors it): one object literal, \`steps: [...]\`, reference outputs with \`$.state.<id>\` / \`$.req.body\`.
 
 \`\`\`typescript
 import { workflow, $ } from "@blokjs/helper";
@@ -1735,7 +1520,7 @@ branch({ id: "route",
 - Do NOT generate class-based \`BlokService\` nodes or use \`any\` types — always \`defineNode()\` (TS) / \`@node\` (Python) with Zod/Pydantic schemas.
 - Do NOT use ESLint/Prettier — this project uses Biome. Do NOT edit auto-generated files in \`.blok/runtimes/\`.
 `;
-const function_first_node_file = `import { defineNode } from "@blokjs/runner";
+const function_first_node_file = `import { defineNode } from "@blokjs/core";
 import { z } from "zod";
 
 /**
@@ -1760,13 +1545,13 @@ export default defineNode({
 	// Execute function - type-safe with inferred types from Zod schemas
 	async execute(ctx, input) {
 		// Your business logic here
-		// - ctx.vars: Access workflow variables
 		// - ctx.request: Access HTTP request data
 		// - ctx.logger: Log messages
 		// - ctx.env: Access environment variables
-
-		// Example: Store data for downstream nodes
-		ctx.vars["processed-message"] = input.message;
+		//
+		// Just RETURN your output — the runner auto-persists it to
+		// ctx.state["{{NODE_NAME}}"], readable from any later step's handle.
+		// Do NOT write to ctx.state / ctx.vars inside a node.
 
 		// Return type-safe output (validated automatically)
 		return {
@@ -1776,4 +1561,4 @@ export default defineNode({
 	},
 });
 `;
-export { node_file, package_dependencies, package_dev_dependencies, python3_file, examples_url, workflow_template, supervisord_nodejs, supervisord_python, go_node_file, go_mod_file, go_dockerfile, java_node_file, java_pom_file, java_dockerfile, rust_node_file, rust_cargo_file, rust_dockerfile, csharp_node_file, csharp_csproj_file, csharp_dockerfile, php_node_file, php_composer_file, php_dockerfile, ruby_node_file, ruby_gemfile, ruby_dockerfile, function_first_node_file, agents_md, claude_md, };
+export { node_file, package_dependencies, package_dev_dependencies, python3_file, examples_url, workflow_template, supervisord_nodejs, supervisord_python, go_node_file, java_node_file, rust_node_file, csharp_node_file, php_node_file, ruby_node_file, function_first_node_file, agents_md, claude_md, };