blokctl 0.2.11 → 0.3.0

package/dist/commands/create/project.js

@@ -135,6 +135,7 @@ export async function createProject(opts, version, currentPath = false, localRep
                             { label: "RabbitMQ", value: "rabbitmq" },
                             { label: "AWS SQS", value: "sqs" },
                             { label: "Redis/BullMQ", value: "redis" },
+                            { label: "NATS JetStream", value: "nats" },
                         ],
                     })
                     : Promise.resolve(null),
@@ -262,6 +263,34 @@ export async function createProject(opts, version, currentPath = false, localRep
                 fsExtra.copySync(src, `${dirPath}/${file}`);
             }
         }
+        const gitignorePath = `${dirPath}/.gitignore`;
+        const gitignoreLine = "\n# Blok Studio trace data (managed by blokctl)\n.blok/\n";
+        if (fsExtra.existsSync(gitignorePath)) {
+            const existing = fsExtra.readFileSync(gitignorePath, "utf8");
+            if (!existing.includes(".blok/")) {
+                fsExtra.appendFileSync(gitignorePath, gitignoreLine);
+            }
+        }
+        else {
+            fsExtra.writeFileSync(gitignorePath, gitignoreLine.trimStart());
+        }
+        fsExtra.ensureDirSync(`${dirPath}/.blok`);
+        fsExtra.writeFileSync(`${dirPath}/.blok/README.md`, [
+            "# .blok/",
+            "",
+            "Auto-generated by `blokctl dev`. This directory holds the SQLite trace",
+            "database that powers Blok Studio (run history, logs, events, dashboards).",
+            "",
+            "- `trace.db` — SQLite file, persists across restarts",
+            "- 7-day retention by default; tune with `BLOK_TRACE_RETENTION_DAYS`",
+            "",
+            "Open it visually with `blokctl studio` (no trigger required — works",
+            "like `prisma studio`). Or wipe everything via the **Clear all data**",
+            "button in Settings.",
+            "",
+            "This directory is gitignored.",
+            "",
+        ].join("\n"));
         if (fsExtra.existsSync(`${primaryTriggerDir}/Dockerfile`)) {
             fsExtra.copySync(`${primaryTriggerDir}/Dockerfile`, `${dirPath}/Dockerfile`);
         }
@@ -539,6 +568,14 @@ export async function createProject(opts, version, currentPath = false, localRep
             console.log(color.dim("    docker compose up -d redis redis-commander"));
             console.log("  Redis Commander UI: http://localhost:8081");
         }
+        if (selectedTriggers.includes("queue") && queueProvider === "nats") {
+            console.log(color.cyan("\n📦 NATS JetStream Setup (for Queue trigger):"));
+            console.log("  Start NATS with Docker:");
+            console.log(color.dim("    cd infra/development"));
+            console.log(color.dim("    docker network create shared-network"));
+            console.log(color.dim("    docker compose up -d nats"));
+            console.log("  NATS Monitoring: http://localhost:8222");
+        }
         console.log("\nFor more documentation, visit https://blok.build/");
         if (examples) {
             console.log(examples_url);
@@ -907,6 +944,12 @@ function updateQueueProvider(triggerDestDir, provider) {
 		port: Number(process.env.REDIS_PORT) || 6379,
 	})`,
         },
+        nats: {
+            importName: "NATSAdapter",
+            init: `new NATSAdapter({
+		servers: (process.env.NATS_SERVERS || "localhost:4222").split(","),
+	})`,
+        },
     };
     const config = adapterConfigs[provider];
     if (!config)
@@ -914,6 +957,12 @@ function updateQueueProvider(triggerDestDir, provider) {
     content = content.replace(/import \{ (\w+), (\w+) \} from ["']@blokjs\/trigger-queue["'];/, `import { ${config.importName}, QueueTrigger } from "@blokjs/trigger-queue";`);
     content = content.replace(/(export default class \w+ extends QueueTrigger \{[\s\S]*?)\n\tprotected adapter = new \w+\(\{[\s\S]*?\}\);/, `$1\n\tprotected adapter = ${config.init};`);
     fsExtra.writeFileSync(serverPath, content);
+    const workflowPath = `${triggerDestDir}/workflows/messages/on-message.ts`;
+    if (fsExtra.existsSync(workflowPath)) {
+        let workflowContent = fsExtra.readFileSync(workflowPath, "utf8");
+        workflowContent = workflowContent.replace(/provider: "kafka"/, `provider: "${provider}"`);
+        fsExtra.writeFileSync(workflowPath, workflowContent);
+    }
 }
 function getProviderDependencies(triggers, pubsubProvider, queueProvider) {
     const deps = {};
@@ -927,6 +976,7 @@ function getProviderDependencies(triggers, pubsubProvider, queueProvider) {
         rabbitmq: { amqplib: "^0.10.9" },
         sqs: { "@aws-sdk/client-sqs": "^3.980.0" },
         redis: { ioredis: "^5.9.2", bullmq: "^5.67.2" },
+        nats: { nats: "^2.28.0" },
     };
     if (triggers.includes("pubsub") && pubsubProviderDeps[pubsubProvider]) {
         Object.assign(deps, pubsubProviderDeps[pubsubProvider]);
@@ -970,6 +1020,10 @@ SQS_QUEUE_URL=`,
 REDIS_HOST=localhost
 REDIS_PORT=6379
 REDIS_PASSWORD=`,
+        nats: `
+# NATS JetStream
+NATS_SERVERS=localhost:4222
+NATS_STREAM_NAME=blok-queue`,
     };
     if (triggers.includes("pubsub") && pubsubEnvVars[pubsubProvider]) {
         lines.push(pubsubEnvVars[pubsubProvider]);

package/dist/commands/create/utils/Examples.d.ts

@@ -12,7 +12,7 @@ declare const package_dev_dependencies: {
 };
 declare const python3_file = "\nfrom core.blok import BlokService\nfrom core.types.context import Context\nfrom core.types.blok_response import BlokResponse\nfrom core.types.global_error import GlobalError\nfrom typing import Any, Dict\nimport traceback\n\nclass Node(BlokService):\n    def __init__(self):\n        BlokService.__init__(self)\n        self.input_schema = {}\n        self.output_schema = {}\n\n    async def handle(self, ctx: Context, inputs: Dict[str, Any]) -> BlokResponse:\n        response = BlokResponse()\n\n        try:\n            response.setSuccess({ \"message\": \"Hello World from Python3!\" })\n        except Exception as error:\n            err = GlobalError(error)\n            err.setCode(500)\n            err.setName(self.name)\n\n            stack_trace = traceback.format_exc()\n            err.setStack(stack_trace)\n            response.success = False\n            response.setError(err)\n\n        return response\n";
 declare const examples_url = "\nExamples:\n1- Open \"workflow-docs.json\" in your browser at http://localhost:4000/workflow-docs\n2- Open \"db-manager.json\" in your browser at http://localhost:4000/db-manager\n3- Open \"dashboard-gen.json\" in your browser at http://localhost:4000/dashboard-gen\n4- Open \"countries.json\" in your browser at http://localhost:4000/countries\n\nFor more documentation, visit src/nodes/examples/README.md. The first three examples require a PostgreSQL database to function.\n";
-declare const workflow_template = "\n{\n\t\"name\": \"\",\n\t\"description\": \"\",\n\t\"version\": \"1.0.0\",\n\t\"trigger\": {\n\t\t\"http\": {\n\t\t\t\"method\": \"GET\",\n\t\t\t\"path\": \"/\",\n\t\t\t\"accept\": \"application/json\"\n\t\t}\n\t},\n\t\"steps\": [\n\t\t{\n\t\t\t\"name\": \"node-name\",\n\t\t\t\"node\": \"node-module-name\",\n\t\t\t\"type\": \"module\"\n\t\t}\n\t],\n\t\"nodes\": {\n\t\t\"name\": {\n\t\t\t\"inputs\": {\n\n\t\t\t}\n\t\t}\n\t}\n}\n";
+declare const workflow_template = "\n{\n\t\"name\": \"My Workflow\",\n\t\"description\": \"What this workflow does\",\n\t\"version\": \"1.0.0\",\n\t\"trigger\": {\n\t\t\"http\": {\n\t\t\t\"method\": \"GET\",\n\t\t\t\"accept\": \"application/json\"\n\t\t}\n\t},\n\t\"steps\": [\n\t\t{\n\t\t\t\"id\": \"echo\",\n\t\t\t\"use\": \"@blokjs/respond\",\n\t\t\t\"inputs\": {\n\t\t\t\t\"body\": \"$.req.body\"\n\t\t\t}\n\t\t}\n\t]\n}\n";
 declare const supervisord_nodejs = "\n[supervisord]\nnodaemon=true\n\n[program:nodejs_app]\ncommand=npm start\ndirectory=/app\nautostart=true\nautorestart=true\nstderr_logfile=/var/log/nodejs.err.log\nstdout_logfile=/var/log/nodejs.out.log\n";
 declare const supervisord_python = "\n[program:python_app]\ncommand=python3 /app/.blok/runtimes/python3/server.py\ndirectory=/app\nautostart=true\nautorestart=true\nstderr_logfile=/var/log/python.err.log\nstdout_logfile=/var/log/python.out.log\n";
 declare const go_node_file = "package main\n\nimport (\n\t\"github.com/blok/sdk\"\n)\n\ntype HelloWorldNode struct{}\n\nfunc (n *HelloWorldNode) Execute(ctx *sdk.Context, config map[string]interface{}) (*sdk.ExecutionResult, error) {\n\t// Access request body\n\tname := \"World\"\n\tif body, ok := ctx.Request.Body.(map[string]interface{}); ok {\n\t\tif nameVal, ok := body[\"name\"].(string); ok {\n\t\t\tname = nameVal\n\t\t}\n\t}\n\n\t// Access configuration\n\tprefix := \"Hello\"\n\tif prefixVal, ok := config[\"prefix\"].(string); ok {\n\t\tprefix = prefixVal\n\t}\n\n\t// Store result in context for downstream nodes\n\tctx.Vars[\"greeting\"] = prefix + \", \" + name + \"!\"\n\n\t// Return successful result\n\treturn &sdk.ExecutionResult{\n\t\tSuccess: true,\n\t\tData: map[string]interface{}{\n\t\t\t\"message\": prefix + \", \" + name + \"!\",\n\t\t\t\"timestamp\": sdk.GetCurrentTimestamp(),\n\t\t\t\"language\": \"Go\",\n\t\t},\n\t\tErrors: nil,\n\t}, nil\n}\n\nfunc main() {\n\t// Register node\n\tregistry := sdk.NewNodeRegistry()\n\tregistry.Register(\"{{NODE_NAME}}\", &HelloWorldNode{})\n\n\t// Start HTTP server\n\tserver := sdk.NewHTTPServer(registry, \":8080\")\n\tif err := server.Start(); err != nil {\n\t\tpanic(err)\n\t}\n}\n";
@@ -33,7 +33,7 @@ declare const php_dockerfile = "FROM php:8.2-cli-alpine AS builder\nWORKDIR /app
 declare const ruby_node_file = "require_relative '../../lib/blok'\n\nmodule Blok\n  module Nodes\n    class {{NODE_NAME_PASCAL}}Node < Blok::NodeHandler\n      def execute(ctx, config)\n        # Access request body\n        name = ctx.request.body.is_a?(Hash) ? ctx.request.body['name'] : nil\n        name ||= 'World'\n\n        # Access configuration\n        prefix = config['prefix'] || 'Hello'\n\n        message = \"#{prefix}, #{name}!\"\n\n        # Store in context for downstream nodes\n        ctx.vars['greeting'] = message\n\n        # Return response\n        {\n          'message' => message,\n          'timestamp' => Time.now.utc.iso8601,\n          'language' => 'Ruby'\n        }\n      end\n    end\n  end\nend\n";
 declare const ruby_gemfile = "source 'https://rubygems.org'\n\nruby '>= 3.1'\n\ngem 'sinatra', '~> 4.0'\ngem 'puma', '~> 6.4'\ngem 'rackup', '~> 2.1'\n";
 declare const ruby_dockerfile = "FROM ruby:3.2-alpine AS builder\nRUN apk add --no-cache build-base\nWORKDIR /app\nCOPY Gemfile Gemfile.lock ./\nRUN bundle install --without development test\n\nFROM ruby:3.2-alpine\nRUN apk --no-cache add ca-certificates wget\nWORKDIR /app\nCOPY --from=builder /usr/local/bundle /usr/local/bundle\nCOPY . .\n\nEXPOSE 8080\nENV PORT=8080\nENV RACK_ENV=production\nHEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\\n  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1\n\nCMD [\"bundle\", \"exec\", \"puma\", \"-b\", \"tcp://0.0.0.0:8080\"]\n";
-declare const agents_md = "# Blok Project\n\nBlok is a TypeScript-first workflow orchestration framework. It executes declarative workflows (JSON or TypeScript DSL) composed of steps (nodes) that run across 8 language runtimes: NodeJS, Python3, Go, Rust, Java, C#, PHP, and Ruby.\n\n## Project Structure\n\n```\n\u251C\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 nodes/             # TypeScript node implementations\n\u251C\u2500\u2500 runtimes/              # Non-NodeJS runtime nodes (Go, Python3, etc.)\n\u2502   \u2514\u2500\u2500 {lang}/nodes/      # Language-specific node implementations\n\u251C\u2500\u2500 workflows/\n\u2502   \u251C\u2500\u2500 json/              # Workflow definitions (JSON)\n\u2502   \u251C\u2500\u2500 yaml/              # Workflow definitions (YAML)\n\u2502   \u2514\u2500\u2500 toml/              # Workflow definitions (TOML)\n\u251C\u2500\u2500 .blok/\n\u2502   \u251C\u2500\u2500 config.json        # Runtime configuration (ports, start commands)\n\u2502   \u2514\u2500\u2500 runtimes/          # Auto-generated runtime scaffolds\n\u251C\u2500\u2500 .env.local             # Environment variables (ports, paths)\n\u2514\u2500\u2500 supervisord.conf       # Process management config\n```\n\n## Commands\n\n```bash\nnpm run dev                # Start dev server (or blokctl dev for multi-runtime)\nnpm run build              # Build project\nnpm test                   # Run tests\nblokctl create node <name> # Scaffold a new node\nblokctl create workflow <n># Scaffold a new workflow\nblokctl trace              # Open Blok Studio (trace visualization)\nblokctl studio             # Alias for blokctl trace\n```\n\n## Context \u2014 Critical Data Flow\n\nThe Context type is the central execution state passed through every step.\n\n```typescript\ntype Context = {\n  id: string;                      // Unique request ID\n  request: RequestContext;          // Incoming request (body, headers, params, query)\n  response: ResponseContext;       // Current step output \u2014 OVERWRITTEN every step\n  vars?: VarsContext;              // Persistent variables \u2014 PERSISTS across workflow\n  config: ConfigContext;           // Node config (inputs resolved by Mapper)\n  env?: EnvContext;                // process.env access\n  logger: LoggerContext;\n  error: ErrorContext;\n};\n```\n\n### The Two Critical Rules\n\n**Rule 1: \\`ctx.response.data\\` is OVERWRITTEN after every step.**\nEach step's output replaces the previous \\`ctx.response.data\\`. If you need a step's output later, store it in \\`ctx.vars\\`.\n\n**Rule 2: \\`ctx.vars\\` PERSISTS across the entire workflow.**\nUse \\`set_var: true\\` on a step to auto-store its output in \\`ctx.vars[stepName]\\`. Downstream steps access it via \\`ctx.vars['step-name']\\`.\n\n### Data Flow Example\n\n```\nStep 1: \"fetch-user\"  (set_var: true)\n  \u2192 ctx.response.data = { id: \"123\", name: \"Alice\" }\n  \u2192 ctx.vars[\"fetch-user\"] = { id: \"123\", name: \"Alice\" }\n\nStep 2: \"transform\"\n  \u2192 ctx.response.data = { result: \"done\" }     \u2190 Step 1 output GONE from response\n  \u2192 ctx.vars[\"fetch-user\"] still available\n\nStep 3: \"output\"\n  \u2192 Can read ctx.vars[\"fetch-user\"].name        \u2190 still \"Alice\"\n```\n\n### Blueprint Mapper \u2014 Expression Resolution\n\nNode inputs support dynamic expressions resolved BEFORE node execution:\n\n```json\n{\n  \"inputs\": {\n    \"userId\": \"js/ctx.request.body.userId\",\n    \"chain\": \"js/ctx.vars['previous-step'].chain\",\n    \"previous\": \"js/ctx.response.data.result\"\n  }\n}\n```\n\nAvailable in js/ expressions: \\`ctx\\`, \\`data\\` (ctx.response.data), \\`func\\` (ctx.func), \\`vars\\` (ctx.vars)\n\n---\n\n## Creating Nodes with defineNode\n\nUse \\`defineNode()\\` for all new nodes. Never use the legacy class-based pattern.\n\n```typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"fetch-user\",\n  description: \"Fetches user by ID\",\n\n  input: z.object({\n    userId: z.string().uuid(),\n  }),\n\n  output: z.object({\n    user: z.object({\n      id: z.string(),\n      name: z.string(),\n      email: z.string().email(),\n    }),\n  }),\n\n  async execute(ctx, input) {\n    const user = await fetchUser(input.userId);\n    return { user };\n  },\n});\n```\n\n### Key Behaviors\n\n- Zod input/output validation runs automatically\n- ZodError is mapped to GlobalError with HTTP 400\n- \\`flow: true\\` nodes return NodeBase[] for conditional execution\n- \\`contentType\\` sets response Content-Type (e.g., \"text/html\")\n- Always \\`export default defineNode(...)\\`\n\n---\n\n## Workflow Structure (JSON)\n\n```json\n{\n  \"name\": \"My Workflow\",\n  \"version\": \"1.0.0\",\n  \"trigger\": {\n    \"http\": { \"method\": \"POST\", \"path\": \"/api/process\", \"accept\": \"application/json\" }\n  },\n  \"steps\": [\n    { \"name\": \"fetch\",   \"node\": \"@blokjs/api-call\", \"type\": \"module\" },\n    { \"name\": \"process\", \"node\": \"my-node\",        \"type\": \"module\", \"set_var\": true },\n    { \"name\": \"go-step\", \"node\": \"chain-test\",     \"type\": \"runtime.go\" }\n  ],\n  \"nodes\": {\n    \"fetch\":   { \"inputs\": { \"url\": \"https://api.example.com\", \"method\": \"GET\" } },\n    \"process\": { \"inputs\": { \"data\": \"js/ctx.response.data\" } },\n    \"go-step\": { \"inputs\": { \"processed\": \"js/ctx.vars['process']\" } }\n  }\n}\n```\n\n### Step Types\n\n| Type | Description |\n|------|-------------|\n| \\`module\\` | TypeScript node from registered modules |\n| \\`local\\` | TypeScript node from filesystem (NODES_PATH) |\n| \\`runtime.python3\\` | Python3 SDK container (port 9007) |\n| \\`runtime.go\\` | Go SDK container (port 9001) |\n| \\`runtime.rust\\` | Rust SDK container (port 9002) |\n| \\`runtime.java\\` | Java SDK container (port 9003) |\n| \\`runtime.csharp\\` | C# SDK container (port 9004) |\n| \\`runtime.php\\` | PHP SDK container (port 9005) |\n| \\`runtime.ruby\\` | Ruby SDK container (port 9006) |\n\n### Conditional Workflow (if-else)\n\n```json\n{\n  \"nodes\": {\n    \"filter\": {\n      \"conditions\": [\n        {\n          \"type\": \"if\",\n          \"condition\": \"ctx.request.query.active === \\\\\"true\\\\\"\",\n          \"steps\": [{ \"name\": \"active-path\", \"node\": \"handle-active\", \"type\": \"module\" }]\n        },\n        {\n          \"type\": \"else\",\n          \"steps\": [{ \"name\": \"default-path\", \"node\": \"handle-default\", \"type\": \"module\" }]\n        }\n      ]\n    }\n  }\n}\n```\n\n---\n\n## Trigger Types\n\n| Trigger | Example Config |\n|---------|---------------|\n| \\`http\\` | \\`{ \"method\": \"GET\", \"path\": \"/\", \"accept\": \"application/json\" }\\` |\n| \\`grpc\\` | \\`{ \"service\": \"UserService\", \"method\": \"GetUser\" }\\` |\n| \\`cron\\` | \\`{ \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\" }\\` |\n| \\`queue\\` | \\`{ \"provider\": \"kafka\", \"topic\": \"events\" }\\` |\n| \\`pubsub\\` | \\`{ \"provider\": \"gcp\", \"topic\": \"updates\" }\\` |\n| \\`webhook\\` | \\`{ \"source\": \"github\", \"events\": [\"push\"] }\\` |\n| \\`websocket\\` | \\`{ \"events\": [\"message\"], \"path\": \"/ws\" }\\` |\n| \\`sse\\` | \\`{ \"events\": [\"update\"], \"path\": \"/stream\" }\\` |\n| \\`worker\\` | \\`{ \"queue\": \"jobs\", \"concurrency\": 5 }\\` |\n\n---\n\n## Runtime Adapter System\n\nAll non-NodeJS SDKs communicate via HTTP:\n- **POST /execute** \u2014 Execute node with context\n- **GET /health** \u2014 Health check\n\nEnvironment variables: \\`RUNTIME_{LANG}_HOST\\` / \\`RUNTIME_{LANG}_PORT\\`\n\nRuntime nodes auto-save \\`result.data\\` to \\`ctx.vars[stepName]\\`.\n\n---\n\n## Blok Studio\n\nReal-time workflow trace visualization UI.\n\n- Launch: \\`blokctl trace\\` or \\`blokctl studio\\`\n- API: \\`/__blok/runs\\`, \\`/__blok/runs/:id\\`, \\`/__blok/runs/:id/stream\\` (SSE)\n- Disable: \\`BLOK_TRACE_ENABLED=false\\`\n\n---\n\n## Do NOT\n\n- Do NOT rely on \\`ctx.response.data\\` for data from non-previous steps \u2014 it gets overwritten\n- Do NOT create class-based nodes \u2014 use \\`defineNode()\\` instead\n- Do NOT use \\`any\\` type \u2014 use \\`unknown\\` and narrow with Zod\n- Do NOT hardcode runtime ports \u2014 use environment variables\n- Do NOT skip Zod input/output schemas\n- Do NOT edit files in \\`.blok/runtimes/\\` \u2014 they are auto-generated\n\n## Do\n\n- Use \\`ctx.vars\\` with \\`set_var: true\\` to pass data between non-adjacent steps\n- Use \\`js/ctx.vars['step-name'].field\\` in workflow inputs for data flow\n- Use Zod schemas for all input/output validation\n- Use \\`defineNode()\\` for all new nodes\n- Handle errors via GlobalError with appropriate HTTP status codes\n- Keep nodes focused \u2014 one responsibility per node\n";
-declare const claude_md = "# Blok Project \u2014 Claude Code Guide\n\nRead \\`AGENTS.md\\` for full architecture and API details. This file contains Claude-specific guidance.\n\n## Quick Commands\n\n\\`\\`\\`bash\nnpm run dev                        # Start dev server\nblokctl dev                        # Multi-runtime dev server\nblokctl create node <name>         # Scaffold new node\nblokctl create workflow <name>     # Scaffold new workflow\nblokctl trace                      # Open Blok Studio\nnpm test                           # Run tests\n\\`\\`\\`\n\n## Context Rules (Memorize These)\n\n1. **\\`ctx.response.data\\` is OVERWRITTEN every step.** Previous output GONE unless stored in vars.\n2. **\\`ctx.vars\\` PERSISTS across the workflow.** Use \\`set_var: true\\` or \\`js/ctx.vars['step']\\`.\n3. **Blueprint Mapper resolves \\`js/\\` expressions BEFORE node execution.**\n\nWhen users have data flow issues, check these three things first.\n\n## Debugging Workflows\n\n1. **Verify structure**: Every \\`steps[].name\\` must match a key in \\`nodes\\`\n2. **Trace data flow**: Which steps have \\`set_var: true\\`? Do \\`js/\\` expressions reference correct step names?\n3. **Check runtimes**: SDK containers running? \\`GET http://localhost:{port}/health\\`\n4. **Check Studio traces**: \\`/__blok/runs/:id\\` shows step-by-step inputs/outputs/errors\n\n### Common Errors\n\n| Error | Fix |\n|-------|-----|\n| \\`Node type X not found\\` | Wrong \\`type\\` in step \u2014 use module, local, or runtime.* |\n| \\`Validation failed\\` | Zod schema mismatch \u2014 check input schema vs actual data |\n| \\`Runtime execution error\\` | SDK container not running \u2014 check health endpoint |\n| \\`ctx.vars['X'] undefined\\` | Source step missing \\`set_var: true\\` or name mismatch |\n\n## Generating Code\n\nAlways use \\`defineNode()\\`. Never class-based BlokService.\n\n\\`\\`\\`typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"node-name\",\n  description: \"What this node does\",\n  input: z.object({ /* Zod schema */ }),\n  output: z.object({ /* Zod schema */ }),\n  async execute(ctx, input) {\n    return { /* must match output schema */ };\n  },\n});\n\\`\\`\\`\n\n### Checklist:\n- Zod input schema covers all inputs\n- Zod output schema matches execute() return\n- Node name matches workflow references\n- No \\`any\\` types \u2014 use \\`z.unknown()\\` if dynamic\n- \\`export default defineNode(...)\\`\n\n## Blok Studio Help\n\n- Launch: \\`blokctl trace\\` or navigate to \\`/__blok\\`\n- \"No output\" \u2192 Node not returning data or Zod output validation failed\n- \"Step error\" \u2192 Expand error \u2014 check if 400 (validation) or 500 (runtime)\n- \"Vars not passing\" \u2192 Source step needs \\`set_var: true\\`, target needs \\`js/ctx.vars['name']\\`\n\n## Do NOT\n\n- Do NOT suggest class-based BlokService for new nodes\n- Do NOT generate code with \\`any\\` types\n- Do NOT assume \\`ctx.response.data\\` persists across steps\n- Do NOT skip Zod schemas when creating nodes\n- Do NOT edit files in \\`.blok/runtimes/\\`\n";
+declare const agents_md = "# Blok Project\n\nBlok is a TypeScript-first workflow orchestration framework. It executes declarative workflows (JSON or TypeScript DSL) composed of steps (nodes) that run across 8 language runtimes: NodeJS, Python3, Go, Rust, Java, C#, PHP, and Ruby.\n\n## Project Structure\n\n```\n\u251C\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 nodes/             # TypeScript node implementations\n\u251C\u2500\u2500 runtimes/              # Non-NodeJS runtime nodes (Go, Python3, etc.)\n\u2502   \u2514\u2500\u2500 {lang}/nodes/      # Language-specific node implementations\n\u251C\u2500\u2500 workflows/\n\u2502   \u251C\u2500\u2500 json/              # Workflow definitions (JSON)\n\u2502   \u251C\u2500\u2500 yaml/              # Workflow definitions (YAML)\n\u2502   \u2514\u2500\u2500 toml/              # Workflow definitions (TOML)\n\u251C\u2500\u2500 .blok/\n\u2502   \u251C\u2500\u2500 config.json        # Runtime configuration (ports, start commands)\n\u2502   \u2514\u2500\u2500 runtimes/          # Auto-generated runtime scaffolds\n\u251C\u2500\u2500 .env.local             # Environment variables (ports, paths)\n\u2514\u2500\u2500 supervisord.conf       # Process management config\n```\n\n## Commands\n\n```bash\nnpm run dev                # Start dev server (or blokctl dev for multi-runtime)\nnpm run build              # Build project\nnpm test                   # Run tests\nblokctl create node <name> # Scaffold a new node\nblokctl create workflow <n># Scaffold a new workflow\nblokctl trace              # Open Blok Studio (trace visualization)\nblokctl studio             # Alias for blokctl trace\n```\n\n## Context \u2014 Critical Data Flow\n\nThe Context type is the central execution state passed through every step.\n\n```typescript\ntype Context = {\n  id: string;                      // Unique request ID\n  request: RequestContext;          // Incoming request (body, headers, params, query)\n  response: ResponseContext;       // Current step output \u2014 OVERWRITTEN every step\n  vars?: VarsContext;              // Persistent variables \u2014 PERSISTS across workflow\n  config: ConfigContext;           // Node config (inputs resolved by Mapper)\n  env?: EnvContext;                // process.env access\n  logger: LoggerContext;\n  error: ErrorContext;\n};\n```\n\n### The Two Critical Rules\n\n**Rule 1: \\`ctx.response.data\\` is OVERWRITTEN after every step.**\nEach step's output replaces the previous \\`ctx.response.data\\`. If you need a step's output later, store it in \\`ctx.vars\\`.\n\n**Rule 2: \\`ctx.vars\\` PERSISTS across the entire workflow.**\nUse \\`set_var: true\\` on a step to auto-store its output in \\`ctx.vars[stepName]\\`. Downstream steps access it via \\`ctx.vars['step-name']\\`.\n\n### Data Flow Example\n\n```\nStep 1: \"fetch-user\"  (set_var: true)\n  \u2192 ctx.response.data = { id: \"123\", name: \"Alice\" }\n  \u2192 ctx.vars[\"fetch-user\"] = { id: \"123\", name: \"Alice\" }\n\nStep 2: \"transform\"\n  \u2192 ctx.response.data = { result: \"done\" }     \u2190 Step 1 output GONE from response\n  \u2192 ctx.vars[\"fetch-user\"] still available\n\nStep 3: \"output\"\n  \u2192 Can read ctx.vars[\"fetch-user\"].name        \u2190 still \"Alice\"\n```\n\n### Blueprint Mapper \u2014 Expression Resolution\n\nNode inputs support dynamic expressions resolved BEFORE node execution:\n\n```json\n{\n  \"inputs\": {\n    \"userId\": \"js/ctx.request.body.userId\",\n    \"chain\": \"js/ctx.vars['previous-step'].chain\",\n    \"previous\": \"js/ctx.response.data.result\"\n  }\n}\n```\n\nAvailable in js/ expressions: \\`ctx\\`, \\`data\\` (ctx.response.data), \\`func\\` (ctx.func), \\`vars\\` (ctx.vars)\n\n---\n\n## Creating Nodes with defineNode\n\nUse \\`defineNode()\\` for all new nodes. Never use the legacy class-based pattern.\n\n```typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"fetch-user\",\n  description: \"Fetches user by ID\",\n\n  input: z.object({\n    userId: z.string().uuid(),\n  }),\n\n  output: z.object({\n    user: z.object({\n      id: z.string(),\n      name: z.string(),\n      email: z.string().email(),\n    }),\n  }),\n\n  async execute(ctx, input) {\n    const user = await fetchUser(input.userId);\n    return { user };\n  },\n});\n```\n\n### Key Behaviors\n\n- Zod input/output validation runs automatically\n- ZodError is mapped to GlobalError with HTTP 400\n- \\`flow: true\\` nodes return NodeBase[] for conditional execution\n- \\`contentType\\` sets response Content-Type (e.g., \"text/html\")\n- Always \\`export default defineNode(...)\\`\n\n---\n\n## Workflow Structure (JSON)\n\n```json\n{\n  \"name\": \"My Workflow\",\n  \"version\": \"1.0.0\",\n  \"trigger\": {\n    \"http\": { \"method\": \"POST\", \"path\": \"/api/process\", \"accept\": \"application/json\" }\n  },\n  \"steps\": [\n    { \"name\": \"fetch\",   \"node\": \"@blokjs/api-call\", \"type\": \"module\" },\n    { \"name\": \"process\", \"node\": \"my-node\",        \"type\": \"module\", \"set_var\": true },\n    { \"name\": \"go-step\", \"node\": \"chain-test\",     \"type\": \"runtime.go\" }\n  ],\n  \"nodes\": {\n    \"fetch\":   { \"inputs\": { \"url\": \"https://api.example.com\", \"method\": \"GET\" } },\n    \"process\": { \"inputs\": { \"data\": \"js/ctx.response.data\" } },\n    \"go-step\": { \"inputs\": { \"processed\": \"js/ctx.vars['process']\" } }\n  }\n}\n```\n\n### Step Types\n\n| Type | Description |\n|------|-------------|\n| \\`module\\` | TypeScript node from registered modules |\n| \\`local\\` | TypeScript node from filesystem (NODES_PATH) |\n| \\`runtime.python3\\` | Python3 SDK container (port 9007) |\n| \\`runtime.go\\` | Go SDK container (port 9001) |\n| \\`runtime.rust\\` | Rust SDK container (port 9002) |\n| \\`runtime.java\\` | Java SDK container (port 9003) |\n| \\`runtime.csharp\\` | C# SDK container (port 9004) |\n| \\`runtime.php\\` | PHP SDK container (port 9005) |\n| \\`runtime.ruby\\` | Ruby SDK container (port 9006) |\n\n### Conditional Workflow (if-else)\n\n```json\n{\n  \"nodes\": {\n    \"filter\": {\n      \"conditions\": [\n        {\n          \"type\": \"if\",\n          \"condition\": \"ctx.request.query.active === \\\\\"true\\\\\"\",\n          \"steps\": [{ \"name\": \"active-path\", \"node\": \"handle-active\", \"type\": \"module\" }]\n        },\n        {\n          \"type\": \"else\",\n          \"steps\": [{ \"name\": \"default-path\", \"node\": \"handle-default\", \"type\": \"module\" }]\n        }\n      ]\n    }\n  }\n}\n```\n\n---\n\n## Trigger Types\n\n| Trigger | Example Config |\n|---------|---------------|\n| \\`http\\` | \\`{ \"method\": \"GET\", \"path\": \"/\", \"accept\": \"application/json\" }\\` |\n| \\`grpc\\` | \\`{ \"service\": \"UserService\", \"method\": \"GetUser\" }\\` |\n| \\`cron\\` | \\`{ \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\" }\\` |\n| \\`queue\\` | \\`{ \"provider\": \"kafka\", \"topic\": \"events\" }\\` |\n| \\`pubsub\\` | \\`{ \"provider\": \"gcp\", \"topic\": \"updates\" }\\` |\n| \\`webhook\\` | \\`{ \"source\": \"github\", \"events\": [\"push\"] }\\` |\n| \\`websocket\\` | \\`{ \"events\": [\"message\"], \"path\": \"/ws\" }\\` |\n| \\`sse\\` | \\`{ \"events\": [\"update\"], \"path\": \"/stream\" }\\` |\n| \\`worker\\` | \\`{ \"queue\": \"jobs\", \"concurrency\": 5, \"retries\": 3 }\\` |\n\n### Worker Trigger\n\nThe worker trigger processes background jobs from a queue with retry logic and concurrency control.\n\n\\`\\`\\`typescript\nWorkflow({ name: \"Process Job\", version: \"1.0.0\" })\n  .addTrigger(\"worker\", { queue: \"background-jobs\" })\n  .addStep({\n    name: \"process\",\n    node: \"my-processor\",\n    type: \"module\",\n    inputs: { payload: \"js/ctx.request.body\", jobId: \"js/ctx.request.params.jobId\" },\n  });\n\\`\\`\\`\n\nJob context: \\`ctx.request.body\\` = payload, \\`ctx.request.params.queue\\` = queue name, \\`ctx.request.params.jobId\\` = job ID, \\`ctx.request.params.attempt\\` = attempt count, \\`ctx.vars._worker_job\\` = full metadata.\n\nAdapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev only).\n\n### NATS JetStream\n\nRecommended queue/worker backend. Environment variables:\n\\`\\`\\`\nNATS_SERVERS=localhost:4222\nNATS_STREAM_NAME=blok-queue     # or blok-worker for worker trigger\nNATS_TOKEN=                      # optional auth\n\\`\\`\\`\n\nQueue providers: \\`kafka\\`, \\`rabbitmq\\`, \\`sqs\\`, \\`redis\\`, \\`beanstalk\\`, \\`nats\\`\n\n### Standalone Workers (Go, Rust, Python)\n\nGo, Rust, and Python SDKs include standalone NATS workers that connect directly to NATS without the TypeScript runner:\n\n\\`\\`\\`\nWORKER_CONCURRENCY=1             # Max concurrent jobs\nWORKER_MAX_RETRIES=3             # Max delivery attempts\nWORKER_QUEUES=queue1,queue2      # Queues to consume\n\\`\\`\\`\n\n---\n\n## Testing Utilities\n\n\\`@blokjs/runner\\` provides testing utilities for nodes and workflows.\n\n### NodeTestHarness \u2014 Unit test a single node:\n\\`\\`\\`typescript\nimport { NodeTestHarness } from \"@blokjs/runner\";\nconst harness = new NodeTestHarness(myNode);\nconst result = await harness.execute({ input: \"data\" });\nharness.assertSuccess(result);\nharness.assertOutput(result, { expected: \"output\" });\n\\`\\`\\`\n\n### WorkflowTestRunner \u2014 Integration test a workflow:\n\\`\\`\\`typescript\nimport { WorkflowTestRunner } from \"@blokjs/runner\";\nconst runner = new WorkflowTestRunner({ verbose: true });\nrunner.registerNode(\"validate\", ValidateNode);\nrunner.mockNode(\"external-api\", async (input) => ({ result: \"mocked\" }));\nrunner.loadWorkflow(workflowDefinition);\nconst result = await runner.execute({ input: \"data\" });\n// result.success, result.output, result.trace, result.nodeResults\n\\`\\`\\`\n\n---\n\n## Runtime Adapter System\n\nAll non-NodeJS SDKs communicate via HTTP:\n- **POST /execute** \u2014 Execute node with context\n- **GET /health** \u2014 Health check\n\nEnvironment variables: \\`RUNTIME_{LANG}_HOST\\` / \\`RUNTIME_{LANG}_PORT\\`\n\nRuntime nodes auto-save \\`result.data\\` to \\`ctx.vars[stepName]\\`.\n\n---\n\n## Blok Studio\n\nReal-time workflow trace visualization UI.\n\n- Launch: \\`blokctl trace\\` or \\`blokctl studio\\`\n- API: \\`/__blok/runs\\`, \\`/__blok/runs/:id\\`, \\`/__blok/runs/:id/stream\\` (SSE)\n- Disable: \\`BLOK_TRACE_ENABLED=false\\`\n\n---\n\n## Do NOT\n\n- Do NOT rely on \\`ctx.response.data\\` for data from non-previous steps \u2014 it gets overwritten\n- Do NOT create class-based nodes \u2014 use \\`defineNode()\\` instead\n- Do NOT use \\`any\\` type \u2014 use \\`unknown\\` and narrow with Zod\n- Do NOT hardcode runtime ports \u2014 use environment variables\n- Do NOT skip Zod input/output schemas\n- Do NOT edit files in \\`.blok/runtimes/\\` \u2014 they are auto-generated\n\n## Do\n\n- Use \\`ctx.vars\\` with \\`set_var: true\\` to pass data between non-adjacent steps\n- Use \\`js/ctx.vars['step-name'].field\\` in workflow inputs for data flow\n- Use Zod schemas for all input/output validation\n- Use \\`defineNode()\\` for all new nodes\n- Handle errors via GlobalError with appropriate HTTP status codes\n- Keep nodes focused \u2014 one responsibility per node\n";
+declare const claude_md = "# Blok Project \u2014 Claude Code Guide\n\nRead \\`AGENTS.md\\` for full architecture and API details. This file contains Claude-specific guidance.\n\n## Quick Commands\n\n\\`\\`\\`bash\nnpm run dev                        # Start dev server\nblokctl dev                        # Multi-runtime dev server\nblokctl create node <name>         # Scaffold new node\nblokctl create workflow <name>     # Scaffold new workflow\nblokctl trace                      # Open Blok Studio\nnpm test                           # Run tests\n\\`\\`\\`\n\n## Context Rules (Memorize These)\n\n1. **\\`ctx.response.data\\` is OVERWRITTEN every step.** Previous output GONE unless stored in vars.\n2. **\\`ctx.vars\\` PERSISTS across the workflow.** Use \\`set_var: true\\` or \\`js/ctx.vars['step']\\`.\n3. **Blueprint Mapper resolves \\`js/\\` expressions BEFORE node execution.**\n\nWhen users have data flow issues, check these three things first.\n\n## Debugging Workflows\n\n1. **Verify structure**: Every \\`steps[].name\\` must match a key in \\`nodes\\`\n2. **Trace data flow**: Which steps have \\`set_var: true\\`? Do \\`js/\\` expressions reference correct step names?\n3. **Check runtimes**: SDK containers running? \\`GET http://localhost:{port}/health\\`\n4. **Check Studio traces**: \\`/__blok/runs/:id\\` shows step-by-step inputs/outputs/errors\n\n### Common Errors\n\n| Error | Fix |\n|-------|-----|\n| \\`Node type X not found\\` | Wrong \\`type\\` in step \u2014 use module, local, or runtime.* |\n| \\`Validation failed\\` | Zod schema mismatch \u2014 check input schema vs actual data |\n| \\`Runtime execution error\\` | SDK container not running \u2014 check health endpoint |\n| \\`ctx.vars['X'] undefined\\` | Source step missing \\`set_var: true\\` or name mismatch |\n\n## Generating Code\n\nAlways use \\`defineNode()\\`. Never class-based BlokService.\n\n\\`\\`\\`typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"node-name\",\n  description: \"What this node does\",\n  input: z.object({ /* Zod schema */ }),\n  output: z.object({ /* Zod schema */ }),\n  async execute(ctx, input) {\n    return { /* must match output schema */ };\n  },\n});\n\\`\\`\\`\n\n### Checklist:\n- Zod input schema covers all inputs\n- Zod output schema matches execute() return\n- Node name matches workflow references\n- No \\`any\\` types \u2014 use \\`z.unknown()\\` if dynamic\n- \\`export default defineNode(...)\\`\n\n## Worker Workflows\n\nWorker trigger processes background jobs from a queue:\n\n\\`\\`\\`typescript\nWorkflow({ name: \"Process Job\", version: \"1.0.0\" })\n  .addTrigger(\"worker\", { queue: \"background-jobs\" })\n  .addStep({ name: \"process\", node: \"my-processor\", type: \"module\",\n    inputs: { payload: \"js/ctx.request.body\", jobId: \"js/ctx.request.params.jobId\" } });\n\\`\\`\\`\n\nJob data: \\`ctx.request.body\\` = payload, \\`ctx.request.params.queue/jobId/attempt\\` = metadata.\nAdapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev).\n\n## Testing\n\n\\`\\`\\`typescript\nimport { NodeTestHarness, WorkflowTestRunner } from \"@blokjs/runner\";\n\n// Unit test a node\nconst harness = new NodeTestHarness(myNode);\nconst result = await harness.execute({ input: \"data\" });\nharness.assertSuccess(result);\n\n// Integration test a workflow\nconst runner = new WorkflowTestRunner({ mockAllNodes: true });\nrunner.loadWorkflow(definition);\nconst wfResult = await runner.execute({ input: \"data\" });\n\\`\\`\\`\n\n## Blok Studio Help\n\n- Launch: \\`blokctl trace\\` or navigate to \\`/__blok\\`\n- \"No output\" \u2192 Node not returning data or Zod output validation failed\n- \"Step error\" \u2192 Expand error \u2014 check if 400 (validation) or 500 (runtime)\n- \"Vars not passing\" \u2192 Source step needs \\`set_var: true\\`, target needs \\`js/ctx.vars['name']\\`\n\n## Debugging Workers\n\n- NATS not reachable \u2192 Check \\`NATS_SERVERS\\` env var, ensure NATS is running\n- Job timeout \u2192 Increase \\`timeout\\` in trigger config or optimize node\n- Max retries exceeded \u2192 Check node errors, job moves to DLQ\n\n## Do NOT\n\n- Do NOT suggest class-based BlokService for new nodes\n- Do NOT generate code with \\`any\\` types\n- Do NOT assume \\`ctx.response.data\\` persists across steps\n- Do NOT skip Zod schemas when creating nodes\n- Do NOT edit files in \\`.blok/runtimes/\\`\n";
 declare const function_first_node_file = "import { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\n/**\n * A function-first node that demonstrates the modern defineNode pattern.\n * This node is type-safe, validated, and requires 60% less boilerplate.\n */\nexport default defineNode({\n\tname: \"{{NODE_NAME}}\",\n\tdescription: \"A function-first node with Zod validation\",\n\n\t// Input schema using Zod - automatically validated\n\tinput: z.object({\n\t\tmessage: z.string().optional().default(\"Hello World\"),\n\t}),\n\n\t// Output schema using Zod - automatically validated\n\toutput: z.object({\n\t\tmessage: z.string(),\n\t\ttimestamp: z.string(),\n\t}),\n\n\t// Execute function - type-safe with inferred types from Zod schemas\n\tasync execute(ctx, input) {\n\t\t// Your business logic here\n\t\t// - ctx.vars: Access workflow variables\n\t\t// - ctx.request: Access HTTP request data\n\t\t// - ctx.logger: Log messages\n\t\t// - ctx.env: Access environment variables\n\n\t\t// Example: Store data for downstream nodes\n\t\tctx.vars[\"processed-message\"] = input.message;\n\n\t\t// Return type-safe output (validated automatically)\n\t\treturn {\n\t\t\tmessage: `Processed: ${input.message}`,\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t};\n\t},\n});\n";
 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, };

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

@@ -72,30 +72,24 @@ For more documentation, visit src/nodes/examples/README.md. The first three exam
 `;
 const workflow_template = `
 {
-	"name": "",
-	"description": "",
+	"name": "My Workflow",
+	"description": "What this workflow does",
 	"version": "1.0.0",
 	"trigger": {
 		"http": {
 			"method": "GET",
-			"path": "/",
 			"accept": "application/json"
 		}
 	},
 	"steps": [
 		{
-			"name": "node-name",
-			"node": "node-module-name",
-			"type": "module"
-		}
-	],
-	"nodes": {
-		"name": {
+			"id": "echo",
+			"use": "@blokjs/respond",
 			"inputs": {
-
+				"body": "$.req.body"
 			}
 		}
-	}
+	]
 }
 `;
 const supervisord_nodejs = `
@@ -815,7 +809,73 @@ export default defineNode({
 | \\\`webhook\\\` | \\\`{ "source": "github", "events": ["push"] }\\\` |
 | \\\`websocket\\\` | \\\`{ "events": ["message"], "path": "/ws" }\\\` |
 | \\\`sse\\\` | \\\`{ "events": ["update"], "path": "/stream" }\\\` |
-| \\\`worker\\\` | \\\`{ "queue": "jobs", "concurrency": 5 }\\\` |
+| \\\`worker\\\` | \\\`{ "queue": "jobs", "concurrency": 5, "retries": 3 }\\\` |
+
+### Worker Trigger
+
+The worker trigger processes background jobs from a queue with retry logic and concurrency control.
+
+\\\`\\\`\\\`typescript
+Workflow({ name: "Process Job", version: "1.0.0" })
+  .addTrigger("worker", { queue: "background-jobs" })
+  .addStep({
+    name: "process",
+    node: "my-processor",
+    type: "module",
+    inputs: { payload: "js/ctx.request.body", jobId: "js/ctx.request.params.jobId" },
+  });
+\\\`\\\`\\\`
+
+Job context: \\\`ctx.request.body\\\` = payload, \\\`ctx.request.params.queue\\\` = queue name, \\\`ctx.request.params.jobId\\\` = job ID, \\\`ctx.request.params.attempt\\\` = attempt count, \\\`ctx.vars._worker_job\\\` = full metadata.
+
+Adapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev only).
+
+### NATS JetStream
+
+Recommended queue/worker backend. Environment variables:
+\\\`\\\`\\\`
+NATS_SERVERS=localhost:4222
+NATS_STREAM_NAME=blok-queue     # or blok-worker for worker trigger
+NATS_TOKEN=                      # optional auth
+\\\`\\\`\\\`
+
+Queue providers: \\\`kafka\\\`, \\\`rabbitmq\\\`, \\\`sqs\\\`, \\\`redis\\\`, \\\`beanstalk\\\`, \\\`nats\\\`
+
+### Standalone Workers (Go, Rust, Python)
+
+Go, Rust, and Python SDKs include standalone NATS workers that connect directly to NATS without the TypeScript runner:
+
+\\\`\\\`\\\`
+WORKER_CONCURRENCY=1             # Max concurrent jobs
+WORKER_MAX_RETRIES=3             # Max delivery attempts
+WORKER_QUEUES=queue1,queue2      # Queues to consume
+\\\`\\\`\\\`
+
+---
+
+## Testing Utilities
+
+\\\`@blokjs/runner\\\` provides testing utilities for nodes and workflows.
+
+### NodeTestHarness — Unit test a single node:
+\\\`\\\`\\\`typescript
+import { NodeTestHarness } from "@blokjs/runner";
+const harness = new NodeTestHarness(myNode);
+const result = await harness.execute({ input: "data" });
+harness.assertSuccess(result);
+harness.assertOutput(result, { expected: "output" });
+\\\`\\\`\\\`
+
+### WorkflowTestRunner — Integration test a workflow:
+\\\`\\\`\\\`typescript
+import { WorkflowTestRunner } from "@blokjs/runner";
+const runner = new WorkflowTestRunner({ verbose: true });
+runner.registerNode("validate", ValidateNode);
+runner.mockNode("external-api", async (input) => ({ result: "mocked" }));
+runner.loadWorkflow(workflowDefinition);
+const result = await runner.execute({ input: "data" });
+// result.success, result.output, result.trace, result.nodeResults
+\\\`\\\`\\\`
 
 ---
 
@@ -924,6 +984,36 @@ export default defineNode({
 - No \\\`any\\\` types — use \\\`z.unknown()\\\` if dynamic
 - \\\`export default defineNode(...)\\\`
 
+## Worker Workflows
+
+Worker trigger processes background jobs from a queue:
+
+\\\`\\\`\\\`typescript
+Workflow({ name: "Process Job", version: "1.0.0" })
+  .addTrigger("worker", { queue: "background-jobs" })
+  .addStep({ name: "process", node: "my-processor", type: "module",
+    inputs: { payload: "js/ctx.request.body", jobId: "js/ctx.request.params.jobId" } });
+\\\`\\\`\\\`
+
+Job data: \\\`ctx.request.body\\\` = payload, \\\`ctx.request.params.queue/jobId/attempt\\\` = metadata.
+Adapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev).
+
+## Testing
+
+\\\`\\\`\\\`typescript
+import { NodeTestHarness, WorkflowTestRunner } from "@blokjs/runner";
+
+// Unit test a node
+const harness = new NodeTestHarness(myNode);
+const result = await harness.execute({ input: "data" });
+harness.assertSuccess(result);
+
+// Integration test a workflow
+const runner = new WorkflowTestRunner({ mockAllNodes: true });
+runner.loadWorkflow(definition);
+const wfResult = await runner.execute({ input: "data" });
+\\\`\\\`\\\`
+
 ## Blok Studio Help
 
 - Launch: \\\`blokctl trace\\\` or navigate to \\\`/__blok\\\`
@@ -931,6 +1021,12 @@ export default defineNode({
 - "Step error" → Expand error — check if 400 (validation) or 500 (runtime)
 - "Vars not passing" → Source step needs \\\`set_var: true\\\`, target needs \\\`js/ctx.vars['name']\\\`
 
+## Debugging Workers
+
+- NATS not reachable → Check \\\`NATS_SERVERS\\\` env var, ensure NATS is running
+- Job timeout → Increase \\\`timeout\\\` in trigger config or optimize node
+- Max retries exceeded → Check node errors, job moves to DLQ
+
 ## Do NOT
 
 - Do NOT suggest class-based BlokService for new nodes

package/dist/commands/dev/index.js

@@ -2,6 +2,8 @@ import { spawn } from "node:child_process";
 import http from "node:http";
 import path from "node:path";
 import fsExtra from "fs-extra";
+import { waitForGrpcPort } from "../../services/health-probe.js";
+import { detectRr } from "../../services/runtime-detector.js";
 import { readProjectConfig } from "../../services/runtime-setup.js";
 const runningProcesses = [];
 function spawnProcess(cmd, args, name, currentPath, cwd, env) {
@@ -38,7 +40,7 @@ function killAllGroups(signal) {
         }
     }
 }
-function waitForHealth(port, timeoutMs, proc) {
+function waitForHttpHealth(port, timeoutMs, proc) {
     return new Promise((resolve) => {
         if (proc && proc.exitCode !== null) {
             resolve(false);
@@ -74,13 +76,25 @@ function waitForHealth(port, timeoutMs, proc) {
 }
 export async function devProject(opts) {
     const currentPath = process.cwd();
-    console.log("Starting the development server...");
+    const useHttpFallback = opts.withHttpFallback === true;
+    const transport = useHttpFallback ? "http" : "grpc";
+    console.log(`Starting the development server (transport=${transport})...`);
     console.log("Current path: ", currentPath);
+    if (useHttpFallback) {
+        console.log("  ⚠ --with-http-fallback is deprecated and will be removed in v0.4.0.");
+    }
     const config = readProjectConfig(currentPath);
     const runtimeDefs = [];
     if (config?.runtimes) {
         for (const [, rt] of Object.entries(config.runtimes)) {
-            const cmdParts = rt.startCmd.split(" ");
+            let bootCmd = useHttpFallback ? rt.startCmd : (rt.grpcStartCmd ?? rt.startCmd);
+            if (rt.kind === "php" && !useHttpFallback && bootCmd.startsWith("rr ")) {
+                const rrBin = detectRr();
+                if (rrBin && rrBin !== "rr") {
+                    bootCmd = `${rrBin}${bootCmd.slice(2)}`;
+                }
+            }
+            const cmdParts = bootCmd.split(" ");
             const cmd = cmdParts[0];
             const args = cmdParts.slice(1);
             const runtimeCwd = path.resolve(currentPath, rt.cwd);
@@ -88,16 +102,21 @@ export async function devProject(opts) {
                 console.log(`  Warning: ${rt.label} runtime directory not found at ${rt.cwd}. Skipping.`);
                 continue;
             }
+            const grpcPort = rt.grpcPort ?? rt.port + 1000;
+            const probePort = useHttpFallback ? rt.port : grpcPort;
+            const env = {
+                PORT: String(rt.port),
+                GRPC_PORT: String(grpcPort),
+                HOST: "0.0.0.0",
+                BLOK_TRANSPORT: transport,
+            };
             runtimeDefs.push({
                 cmd,
                 args,
-                name: `${rt.label} Runtime (port ${rt.port})`,
+                name: `${rt.label} Runtime (${transport} port ${probePort})`,
                 cwd: runtimeCwd,
-                env: {
-                    PORT: String(rt.port),
-                    HOST: "0.0.0.0",
-                },
-                port: rt.port,
+                env,
+                port: probePort,
             });
         }
     }
@@ -132,15 +151,21 @@ export async function devProject(opts) {
         }
     }
     if (config?.runtimes && Object.keys(config.runtimes).length > 0) {
-        console.log("\nRuntime health endpoints:");
+        console.log("\nRuntime listeners:");
         for (const [, rt] of Object.entries(config.runtimes)) {
-            console.log(`  ${rt.label}: http://localhost:${rt.port}/health`);
+            if (useHttpFallback) {
+                console.log(`  ${rt.label}: http://localhost:${rt.port}/health`);
+            }
+            else {
+                const grpcPort = rt.grpcPort ?? rt.port + 1000;
+                console.log(`  ${rt.label}: gRPC 127.0.0.1:${grpcPort}`);
+            }
         }
     }
     if (healthChecks.length > 0) {
         console.log("\nWaiting for runtimes to be ready...");
         const maxWait = 120_000;
-        const results = await Promise.all(healthChecks.map((hc) => waitForHealth(hc.port, maxWait, hc.proc)));
+        const results = await Promise.all(healthChecks.map((hc) => useHttpFallback ? waitForHttpHealth(hc.port, maxWait, hc.proc) : waitForGrpcPort(hc.port, maxWait, hc.proc)));
         const allReady = results.every(Boolean);
         if (allReady) {
             console.log("All runtimes ready.\n");
@@ -151,6 +176,17 @@ export async function devProject(opts) {
             console.log("Starting NodeJS runner anyway.\n");
         }
     }
+    const traceEnv = {};
+    if (!process.env.BLOK_TRACE_STORE) {
+        traceEnv.BLOK_TRACE_STORE = "sqlite";
+    }
+    if (!process.env.BLOK_TRACE_SQLITE_PATH) {
+        traceEnv.BLOK_TRACE_SQLITE_PATH = path.join(".blok", "trace.db");
+    }
+    const triggerEnv = {
+        ...traceEnv,
+        BLOK_TRANSPORT: transport,
+    };
     if (config?.triggers && Object.keys(config.triggers).length > 0) {
         console.log("Starting triggers...");
         for (const [, trigger] of Object.entries(config.triggers)) {
@@ -162,11 +198,12 @@ export async function devProject(opts) {
             }
             spawnProcess(cmd, args, `${trigger.label} (port ${trigger.port})`, currentPath, undefined, {
                 PORT: String(trigger.port),
+                ...triggerEnv,
             });
         }
     }
     else {
-        spawnProcess("bun", ["--watch", "run", "src/index.ts"], "Blok Runner", currentPath);
+        spawnProcess("bun", ["--watch", "run", "src/index.ts"], "Blok Runner", currentPath, undefined, triggerEnv);
     }
     const keepAlive = setInterval(() => { }, 60_000);
     let stopping = false;

package/dist/commands/generate/validators/WorkflowValidator.js

@@ -12,7 +12,7 @@ const VALID_TRIGGER_TYPES = [
 ];
 const VALID_STEP_TYPES = ["module", "local", "runtime.python3", "runtime.go", "runtime.java"];
 const VALID_HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "ANY", "*"];
-const VALID_QUEUE_PROVIDERS = ["kafka", "rabbitmq", "sqs", "redis", "beanstalk"];
+const VALID_QUEUE_PROVIDERS = ["kafka", "rabbitmq", "sqs", "redis", "beanstalk", "nats"];
 const VALID_PUBSUB_PROVIDERS = ["gcp", "aws", "azure"];
 const VALID_WEBHOOK_SOURCES = ["github", "stripe", "shopify", "custom"];
 export function validateWorkflow(jsonString) {

package/dist/commands/migrate/index.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { program } from "../../services/commander.js";
 import { migrateNode } from "./node.js";
+import { migrateWorkflows } from "./workflows.js";
 const migrate = new Command("migrate").description("Migrate nodes and workflows to newer patterns");
 const node = new Command("node")
     .description("Migrate a class-based node to function-first pattern")
@@ -10,5 +11,15 @@ const node = new Command("node")
     .action(async (options) => {
     await migrateNode(options);
 });
+const workflows = new Command("workflows")
+    .description("Migrate v1 JSON workflows to the v2 shape (id+use+inputs, branch primitive, ANY method)")
+    .option("-d, --dir <value>", "Path to the JSON workflows directory (defaults to ./workflows/json or ./triggers/http/workflows/json)")
+    .option("--dry-run", "Print what would change without writing files")
+    .option("--backup", "Create .bak files next to each migrated workflow (default true)")
+    .option("--no-backup", "Skip backup creation")
+    .action(async (options) => {
+    await migrateWorkflows(options);
+});
 migrate.addCommand(node);
+migrate.addCommand(workflows);
 program.addCommand(migrate);

package/dist/commands/migrate/workflows.d.ts

@@ -0,0 +1,3 @@
+import type { OptionValues } from "commander";
+export declare function migrateWorkflows(opts: OptionValues): Promise<void>;
+export declare function rewriteLegacyExpressions<T>(value: T): T;