blokctl 0.3.0 → 0.6.1

package/dist/commands/check/index.d.ts

@@ -0,0 +1,2 @@
+import type { OptionValues } from "commander";
+export declare function checkProject(_opts: OptionValues): Promise<void>;

package/dist/commands/check/index.js

@@ -0,0 +1,39 @@
+import color from "picocolors";
+import { readProjectConfig, validateProjectRuntimes } from "../../services/runtime-setup.js";
+export async function checkProject(_opts) {
+    const currentPath = process.cwd();
+    const config = readProjectConfig(currentPath);
+    if (!config) {
+        console.error("  No .blok/config.json found. Run this from a Blok project directory.");
+        process.exit(1);
+    }
+    console.log(`\n  ${color.bold("Blok Runtime Version Check")}`);
+    console.log("  ──────────────────────────\n");
+    const results = await validateProjectRuntimes(currentPath);
+    if (results.length === 0) {
+        console.log("  No runtime version constraints configured.");
+        console.log("  Runtime versions will be pinned automatically on next project creation.\n");
+        process.exit(0);
+    }
+    console.log(`  ${color.bold("Project runtimes")} (.blok/config.json):`);
+    for (const r of results) {
+        if (r.satisfied) {
+            console.log(`    ${color.green("✓")} ${r.label}  ${r.found} (requires ${r.required})`);
+        }
+        else {
+            console.log(`    ${color.red("✗")} ${r.label}  ${r.found || "not installed"} (requires ${r.required})`);
+        }
+    }
+    console.log();
+    const failures = results.filter((r) => !r.satisfied);
+    if (failures.length > 0) {
+        for (const f of failures) {
+            console.log(f.message);
+            console.log();
+        }
+        console.log(`  ${color.red(`${failures.length} check${failures.length > 1 ? "s" : ""} failed.`)}\n`);
+        process.exit(1);
+    }
+    console.log(`  ${color.green("All checks passed.")}\n`);
+    process.exit(0);
+}

package/dist/commands/create/project.js

@@ -11,12 +11,13 @@ import { isNonInteractive, parseCommaSeparated, resolveOrThrow } from "../../ser
 import { manager as pm } from "../../services/package-manager.js";
 import { detectRuntimes } from "../../services/runtime-detector.js";
 import { createTriggerConfig, generateRuntimeEnvVars, generateSupervisordConfig, generateTriggerEnvVars, generateTriggerSupervisordConfig, setupRuntime, writeProjectConfig, } from "../../services/runtime-setup.js";
+import { computeDefaultConstraint } from "../../services/semver-utils.js";
 import { agents_md, claude_md, examples_url, node_file, package_dependencies, package_dev_dependencies, } from "./utils/Examples.js";
 const exec = util.promisify(child_process.exec);
 const HOME_DIR = `${os.homedir()}/.blok`;
 const GITHUB_REPO_LOCAL = `${HOME_DIR}/blok`;
 const GITHUB_REPO_REMOTE = "https://github.com/well-prado/blok.git";
-const GITHUB_REPO_RELEASE_TAG = "v0.2.9";
+const GITHUB_REPO_RELEASE_TAG = "v0.6.1";
 fsExtra.ensureDirSync(HOME_DIR);
 const options = {
     baseDir: HOME_DIR,
@@ -86,8 +87,12 @@ export async function createProject(opts, version, currentPath = false, localRep
             { label: "NodeJS", value: "node", hint: "always included" },
             ...detectedRuntimes.map((rt) => {
                 let hint;
-                if (rt.available) {
-                    hint = `${rt.toolchain} ${rt.version || ""} detected`.trim();
+                if (rt.available && rt.version) {
+                    const constraint = computeDefaultConstraint(rt.version);
+                    hint = `${rt.toolchain} ${rt.version} detected (will pin ${constraint})`;
+                }
+                else if (rt.available) {
+                    hint = `${rt.toolchain} detected`;
                 }
                 else if (rt.secondaryTool && !rt.secondaryTool.available) {
                     hint = `${rt.secondaryTool.name} not found - will be skipped`;
@@ -412,6 +417,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             "@blokjs/trigger-pubsub": "triggers/pubsub",
             "@blokjs/trigger-queue": "triggers/queue",
         };
+        const BLOKJS_DEP_RANGE = "^0.6.1";
         for (const depGroup of ["dependencies", "devDependencies", "peerDependencies"]) {
             const deps = packageJsonContent[depGroup];
             if (!deps)
@@ -419,7 +425,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             for (const pkg of Object.keys(deps)) {
                 if (pkg.startsWith("@blok/")) {
                     const newPkg = pkg.replace("@blok/", "@blokjs/");
-                    deps[newPkg] = "^0.2.0";
+                    deps[newPkg] = BLOKJS_DEP_RANGE;
                     delete deps[pkg];
                 }
             }
@@ -429,9 +435,18 @@ export async function createProject(opts, version, currentPath = false, localRep
                         deps[pkg] = `file:${path.resolve(repoSource, workspacePackageMap[pkg])}`;
                     }
                     else {
-                        deps[pkg] = "^0.2.0";
+                        deps[pkg] = BLOKJS_DEP_RANGE;
                     }
                 }
+                else if (typeof ver === "string" &&
+                    (ver === "^0.2.0" ||
+                        ver === "^0.2" ||
+                        ver === "0.2.0" ||
+                        ver.startsWith("^0.2.") ||
+                        ver.startsWith("0.2.")) &&
+                    (pkg.startsWith("@blokjs/") || pkg === "blokctl")) {
+                    deps[pkg] = BLOKJS_DEP_RANGE;
+                }
             }
         }
         if (localRepoPath) {

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

@@ -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, \"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 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.prev\\` carries the immediately previous step's output.**\nEach step's output replaces \\`ctx.prev\\`. Use it for adjacent-step access only.\n\n**Rule 2: \\`ctx.state[id]\\` PERSISTS across the entire workflow.**\nEvery step's output is auto-stored at \\`ctx.state[<step-id>]\\` (the v2 default-store rule). Downstream steps reference it via \\`$.state.<id>\\` (TS DSL) or \\`\"$.state.<id>\"\\` / \\`\"js/ctx.state.<id>\"\\` (JSON). Opt out per step with \\`ephemeral: true\\`.\n\n### Data Flow Example\n\n```\nStep 1: id \"fetch-user\"\n  \u2192 ctx.state[\"fetch-user\"] = { id: \"123\", name: \"Alice\" }\n  \u2192 ctx.prev = { id: \"123\", name: \"Alice\" }\n\nStep 2: id \"transform\"\n  \u2192 ctx.state[\"transform\"] = { result: \"done\" }\n  \u2192 ctx.prev = { result: \"done\" }              \u2190 Step 1 output GONE from prev\n  \u2192 ctx.state[\"fetch-user\"] still available\n\nStep 3: id \"output\"\n  \u2192 Can read ctx.state[\"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\\` (full context), \\`data\\` (ctx.prev.data), \\`func\\` (ctx.func), \\`vars\\` (alias for ctx.state).\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    { \"id\": \"fetch\",   \"use\": \"@blokjs/api-call\", \"inputs\": { \"url\": \"https://api.example.com\", \"method\": \"GET\" } },\n    { \"id\": \"process\", \"use\": \"my-node\",         \"inputs\": { \"data\": \"$.state.fetch\" } },\n    { \"id\": \"go-step\", \"use\": \"chain-test\", \"type\": \"runtime.go\", \"inputs\": { \"processed\": \"$.state.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 \\`$.state.<id>\\` (or \\`js/ctx.state.<id>\\`) to pass data between non-adjacent steps \u2014 every step default-stores its output there\n- Opt out per step with \\`ephemeral: true\\` when the step is a side effect only\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.prev\\` is the immediately previous step's output.** Overwritten every step.\n2. **\\`ctx.state[<id>]\\` PERSISTS across the workflow.** Every step default-stores its output there; reference via \\`$.state.<id>\\` or \\`js/ctx.state.<id>\\`. Opt out with \\`ephemeral: true\\`.\n3. **Blueprint Mapper resolves \\`$.<path>\\` and \\`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 step has an \\`id\\` and a \\`use\\` (v2). v1's \\`name\\` + \\`nodes{}\\` still works but is normalized at load time.\n2. **Trace data flow**: Does the target step reference the correct source id (\\`$.state.<id>\\`)? Did the source step have \\`ephemeral: true\\` accidentally?\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.state['X'] undefined\\` | Source step has \\`ephemeral: true\\`, or the id doesn't match what's referenced in \\`$.state.<id>\\` |\n| \\`set_var, which was removed in v0.5\\` | Drop \\`set_var: true\\` (it's the default) or replace \\`set_var: false\\` with \\`ephemeral: true\\`. Run \\`blokctl migrate workflows\\`. |\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- \"State not passing\" \u2192 Source step has \\`ephemeral: true\\`, OR target's \\`$.state.<id>\\` references a non-existent step id\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

@@ -657,25 +657,26 @@ type Context = {
 
 ### The Two Critical Rules
 
-**Rule 1: \\\`ctx.response.data\\\` is OVERWRITTEN after every step.**
-Each step's output replaces the previous \\\`ctx.response.data\\\`. If you need a step's output later, store it in \\\`ctx.vars\\\`.
+**Rule 1: \\\`ctx.prev\\\` carries the immediately previous step's output.**
+Each step's output replaces \\\`ctx.prev\\\`. Use it for adjacent-step access only.
 
-**Rule 2: \\\`ctx.vars\\\` PERSISTS across the entire workflow.**
-Use \\\`set_var: true\\\` on a step to auto-store its output in \\\`ctx.vars[stepName]\\\`. Downstream steps access it via \\\`ctx.vars['step-name']\\\`.
+**Rule 2: \\\`ctx.state[id]\\\` PERSISTS across the entire workflow.**
+Every step's output is auto-stored at \\\`ctx.state[<step-id>]\\\` (the v2 default-store rule). Downstream steps reference it via \\\`$.state.<id>\\\` (TS DSL) or \\\`"$.state.<id>"\\\` / \\\`"js/ctx.state.<id>"\\\` (JSON). Opt out per step with \\\`ephemeral: true\\\`.
 
 ### Data Flow Example
 
 \`\`\`
-Step 1: "fetch-user"  (set_var: true)
-  → ctx.response.data = { id: "123", name: "Alice" }
-  → ctx.vars["fetch-user"] = { id: "123", name: "Alice" }
+Step 1: id "fetch-user"
+  → ctx.state["fetch-user"] = { id: "123", name: "Alice" }
+  → ctx.prev = { id: "123", name: "Alice" }
 
-Step 2: "transform"
-  → ctx.response.data = { result: "done" }     ← Step 1 output GONE from response
-  → ctx.vars["fetch-user"] still available
+Step 2: id "transform"
+  → ctx.state["transform"] = { result: "done" }
+  → ctx.prev = { result: "done" }              ← Step 1 output GONE from prev
+  → ctx.state["fetch-user"] still available
 
-Step 3: "output"
-  → Can read ctx.vars["fetch-user"].name        ← still "Alice"
+Step 3: id "output"
+  → Can read ctx.state["fetch-user"].name      ← still "Alice"
 \`\`\`
 
 ### Blueprint Mapper — Expression Resolution
@@ -692,7 +693,7 @@ Node inputs support dynamic expressions resolved BEFORE node execution:
 }
 \`\`\`
 
-Available in js/ expressions: \\\`ctx\\\`, \\\`data\\\` (ctx.response.data), \\\`func\\\` (ctx.func), \\\`vars\\\` (ctx.vars)
+Available in js/ expressions: \\\`ctx\\\` (full context), \\\`data\\\` (ctx.prev.data), \\\`func\\\` (ctx.func), \\\`vars\\\` (alias for ctx.state).
 
 ---
 
@@ -747,15 +748,10 @@ export default defineNode({
     "http": { "method": "POST", "path": "/api/process", "accept": "application/json" }
   },
   "steps": [
-    { "name": "fetch",   "node": "@blokjs/api-call", "type": "module" },
-    { "name": "process", "node": "my-node",        "type": "module", "set_var": true },
-    { "name": "go-step", "node": "chain-test",     "type": "runtime.go" }
-  ],
-  "nodes": {
-    "fetch":   { "inputs": { "url": "https://api.example.com", "method": "GET" } },
-    "process": { "inputs": { "data": "js/ctx.response.data" } },
-    "go-step": { "inputs": { "processed": "js/ctx.vars['process']" } }
-  }
+    { "id": "fetch",   "use": "@blokjs/api-call", "inputs": { "url": "https://api.example.com", "method": "GET" } },
+    { "id": "process", "use": "my-node",         "inputs": { "data": "$.state.fetch" } },
+    { "id": "go-step", "use": "chain-test", "type": "runtime.go", "inputs": { "processed": "$.state.process" } }
+  ]
 }
 \`\`\`
 
@@ -912,8 +908,8 @@ Real-time workflow trace visualization UI.
 
 ## Do
 
-- Use \\\`ctx.vars\\\` with \\\`set_var: true\\\` to pass data between non-adjacent steps
-- Use \\\`js/ctx.vars['step-name'].field\\\` in workflow inputs for data flow
+- Use \\\`$.state.<id>\\\` (or \\\`js/ctx.state.<id>\\\`) to pass data between non-adjacent steps — every step default-stores its output there
+- Opt out per step with \\\`ephemeral: true\\\` when the step is a side effect only
 - Use Zod schemas for all input/output validation
 - Use \\\`defineNode()\\\` for all new nodes
 - Handle errors via GlobalError with appropriate HTTP status codes
@@ -936,16 +932,16 @@ npm test                           # Run tests
 
 ## Context Rules (Memorize These)
 
-1. **\\\`ctx.response.data\\\` is OVERWRITTEN every step.** Previous output GONE unless stored in vars.
-2. **\\\`ctx.vars\\\` PERSISTS across the workflow.** Use \\\`set_var: true\\\` or \\\`js/ctx.vars['step']\\\`.
-3. **Blueprint Mapper resolves \\\`js/\\\` expressions BEFORE node execution.**
+1. **\\\`ctx.prev\\\` is the immediately previous step's output.** Overwritten every step.
+2. **\\\`ctx.state[<id>]\\\` PERSISTS across the workflow.** Every step default-stores its output there; reference via \\\`$.state.<id>\\\` or \\\`js/ctx.state.<id>\\\`. Opt out with \\\`ephemeral: true\\\`.
+3. **Blueprint Mapper resolves \\\`$.<path>\\\` and \\\`js/\\\` expressions BEFORE node execution.**
 
 When users have data flow issues, check these three things first.
 
 ## Debugging Workflows
 
-1. **Verify structure**: Every \\\`steps[].name\\\` must match a key in \\\`nodes\\\`
-2. **Trace data flow**: Which steps have \\\`set_var: true\\\`? Do \\\`js/\\\` expressions reference correct step names?
+1. **Verify structure**: Every step has an \\\`id\\\` and a \\\`use\\\` (v2). v1's \\\`name\\\` + \\\`nodes{}\\\` still works but is normalized at load time.
+2. **Trace data flow**: Does the target step reference the correct source id (\\\`$.state.<id>\\\`)? Did the source step have \\\`ephemeral: true\\\` accidentally?
 3. **Check runtimes**: SDK containers running? \\\`GET http://localhost:{port}/health\\\`
 4. **Check Studio traces**: \\\`/__blok/runs/:id\\\` shows step-by-step inputs/outputs/errors
 
@@ -956,7 +952,8 @@ When users have data flow issues, check these three things first.
 | \\\`Node type X not found\\\` | Wrong \\\`type\\\` in step — use module, local, or runtime.* |
 | \\\`Validation failed\\\` | Zod schema mismatch — check input schema vs actual data |
 | \\\`Runtime execution error\\\` | SDK container not running — check health endpoint |
-| \\\`ctx.vars['X'] undefined\\\` | Source step missing \\\`set_var: true\\\` or name mismatch |
+| \\\`ctx.state['X'] undefined\\\` | Source step has \\\`ephemeral: true\\\`, or the id doesn't match what's referenced in \\\`$.state.<id>\\\` |
+| \\\`set_var, which was removed in v0.5\\\` | Drop \\\`set_var: true\\\` (it's the default) or replace \\\`set_var: false\\\` with \\\`ephemeral: true\\\`. Run \\\`blokctl migrate workflows\\\`. |
 
 ## Generating Code
 
@@ -1019,7 +1016,7 @@ const wfResult = await runner.execute({ input: "data" });
 - Launch: \\\`blokctl trace\\\` or navigate to \\\`/__blok\\\`
 - "No output" → Node not returning data or Zod output validation failed
 - "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']\\\`
+- "State not passing" → Source step has \\\`ephemeral: true\\\`, OR target's \\\`$.state.<id>\\\` references a non-existent step id
 
 ## Debugging Workers
 

package/dist/commands/dev/index.js

@@ -1,10 +1,9 @@
 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";
+import { readProjectConfig, validateProjectRuntimes } from "../../services/runtime-setup.js";
 const runningProcesses = [];
 function spawnProcess(cmd, args, name, currentPath, cwd, env) {
     const child = spawn(cmd, args, {
@@ -40,55 +39,45 @@ function killAllGroups(signal) {
         }
     }
 }
-function waitForHttpHealth(port, timeoutMs, proc) {
-    return new Promise((resolve) => {
-        if (proc && proc.exitCode !== null) {
-            resolve(false);
-            return;
-        }
-        const start = Date.now();
-        let done = false;
-        function finish(result) {
-            if (done)
-                return;
-            done = true;
-            clearInterval(interval);
-            resolve(result);
-        }
-        proc?.on("exit", () => finish(false));
-        const interval = setInterval(() => {
-            if (done)
-                return;
-            if (Date.now() - start > timeoutMs) {
-                finish(false);
-                return;
-            }
-            const req = http.get(`http://localhost:${port}/health`, (res) => {
-                res.resume();
-                if (res.statusCode === 200)
-                    finish(true);
-            });
-            req.on("error", () => {
-            });
-            req.setTimeout(1000, () => req.destroy());
-        }, 500);
-    });
-}
 export async function devProject(opts) {
     const currentPath = process.cwd();
-    const useHttpFallback = opts.withHttpFallback === true;
-    const transport = useHttpFallback ? "http" : "grpc";
-    console.log(`Starting the development server (transport=${transport})...`);
+    console.log("Starting the development server (transport=grpc)...");
     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 skipVersionCheck = opts.skipVersionCheck === true;
+    const validationResults = await validateProjectRuntimes(currentPath);
+    if (validationResults.length > 0) {
+        const failures = validationResults.filter((r) => !r.satisfied);
+        const successes = validationResults.filter((r) => r.satisfied);
+        if (failures.length > 0 && !skipVersionCheck) {
+            console.error("\n  Runtime version requirements not met:\n");
+            for (const f of failures) {
+                console.error(f.message);
+                console.error();
+            }
+            console.error("  Tip: Use --skip-version-check to bypass this check.\n");
+            process.exit(1);
+        }
+        if (failures.length > 0 && skipVersionCheck) {
+            console.log("\n  Runtime version warnings:");
+            for (const f of failures) {
+                console.log(`  ! ${f.label}  ${f.found || "not installed"} (requires ${f.required}) — SKIPPED`);
+            }
+        }
+        if (successes.length > 0) {
+            if (failures.length === 0)
+                console.log("\n  Runtime version check:");
+            for (const s of successes) {
+                console.log(s.message);
+            }
+        }
+        console.log();
+    }
     const runtimeDefs = [];
     if (config?.runtimes) {
         for (const [, rt] of Object.entries(config.runtimes)) {
-            let bootCmd = useHttpFallback ? rt.startCmd : (rt.grpcStartCmd ?? rt.startCmd);
-            if (rt.kind === "php" && !useHttpFallback && bootCmd.startsWith("rr ")) {
+            let bootCmd = rt.grpcStartCmd ?? rt.startCmd;
+            if (rt.kind === "php" && bootCmd.startsWith("rr ")) {
                 const rrBin = detectRr();
                 if (rrBin && rrBin !== "rr") {
                     bootCmd = `${rrBin}${bootCmd.slice(2)}`;
@@ -103,20 +92,19 @@ export async function devProject(opts) {
                 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,
+                BLOK_TRANSPORT: "grpc",
             };
             runtimeDefs.push({
                 cmd,
                 args,
-                name: `${rt.label} Runtime (${transport} port ${probePort})`,
+                name: `${rt.label} Runtime (grpc port ${grpcPort})`,
                 cwd: runtimeCwd,
                 env,
-                port: probePort,
+                port: grpcPort,
             });
         }
     }
@@ -153,19 +141,14 @@ export async function devProject(opts) {
     if (config?.runtimes && Object.keys(config.runtimes).length > 0) {
         console.log("\nRuntime listeners:");
         for (const [, rt] of Object.entries(config.runtimes)) {
-            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}`);
-            }
+            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) => useHttpFallback ? waitForHttpHealth(hc.port, maxWait, hc.proc) : waitForGrpcPort(hc.port, maxWait, hc.proc)));
+        const results = await Promise.all(healthChecks.map((hc) => waitForGrpcPort(hc.port, maxWait, hc.proc)));
         const allReady = results.every(Boolean);
         if (allReady) {
             console.log("All runtimes ready.\n");
@@ -185,7 +168,7 @@ export async function devProject(opts) {
     }
     const triggerEnv = {
         ...traceEnv,
-        BLOK_TRANSPORT: transport,
+        BLOK_TRANSPORT: "grpc",
     };
     if (config?.triggers && Object.keys(config.triggers).length > 0) {
         console.log("Starting triggers...");

package/dist/commands/generate/GenerationAnalytics.js

@@ -106,7 +106,8 @@ export class GenerationAnalytics {
             filtered = filtered.filter((e) => e.success === filter.success);
         }
         if (filter?.since) {
-            filtered = filtered.filter((e) => e.timestamp >= filter.since);
+            const since = filter.since;
+            filtered = filtered.filter((e) => e.timestamp >= since);
         }
         return filtered;
     }

package/dist/commands/generate/e2e/NodeGenerator.e2e.test.js

@@ -197,7 +197,7 @@ describe("NodeGenerator E2E", () => {
     });
     describe("code with markdown fences", () => {
         it("should return code as-is from LLM (cleanup happens at CLI layer)", async () => {
-            const wrappedCode = "```typescript\n" + VALID_FUNCTION_FIRST_NODE + "\n```";
+            const wrappedCode = `\`\`\`typescript\n${VALID_FUNCTION_FIRST_NODE}\n\`\`\``;
             mockedGenerateText.mockResolvedValueOnce({ text: wrappedCode });
             mockValidPass();
             const result = await generator.generateNode("fetch-user", "Create a user fetcher", "test-api-key", false, "function");

package/dist/commands/generate/e2e/TriggerGenerator.e2e.test.js

@@ -252,7 +252,7 @@ describe("TriggerGenerator E2E", () => {
     });
     describe("markdown fence cleanup", () => {
         it("should strip markdown TypeScript fences from LLM response", async () => {
-            const wrappedCode = "```typescript\n" + VALID_QUEUE_TRIGGER + "\n```";
+            const wrappedCode = `\`\`\`typescript\n${VALID_QUEUE_TRIGGER}\n\`\`\``;
             mockedGenerateText.mockResolvedValueOnce({ text: wrappedCode });
             mockedValidateCode.mockReturnValue({ success: true, errors: [], warnings: [] });
             const result = await generator.generateTrigger("kafka-queue", "queue", "Create a queue trigger", "test-api-key");

package/dist/commands/generate/e2e/WorkflowGenerator.e2e.test.js

@@ -210,7 +210,7 @@ describe("WorkflowGenerator E2E", () => {
     });
     describe("markdown fence cleanup", () => {
         it("should strip markdown JSON fences from LLM response", async () => {
-            const wrappedJson = "```json\n" + VALID_HTTP_WORKFLOW + "\n```";
+            const wrappedJson = `\`\`\`json\n${VALID_HTTP_WORKFLOW}\n\`\`\``;
             mockedGenerateText.mockResolvedValueOnce({
                 text: wrappedJson,
             });

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 { migratePaths } from "./paths.js";
 import { migrateWorkflows } from "./workflows.js";
 const migrate = new Command("migrate").description("Migrate nodes and workflows to newer patterns");
 const node = new Command("node")
@@ -20,6 +21,16 @@ const workflows = new Command("workflows")
     .action(async (options) => {
     await migrateWorkflows(options);
 });
+const paths = new Command("paths")
+    .description("Add explicit `trigger.http.path` to every JSON HTTP workflow (prep for v0.4 explicit-path-only routing)")
+    .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 migratePaths(options);
+});
 migrate.addCommand(node);
 migrate.addCommand(workflows);
+migrate.addCommand(paths);
 program.addCommand(migrate);

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

@@ -0,0 +1,2 @@
+import type { OptionValues } from "commander";
+export declare function migratePaths(opts: OptionValues): Promise<void>;