blokctl 0.7.0 → 1.1.0

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

@@ -1,21 +1,25 @@
-const node_file = `import ApiCall from "@blokjs/api-call";
+const node_file = `import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ApiCall from "@blokjs/api-call";
 import IfElse from "@blokjs/if-else";
+import { discoverNodes } from "@blokjs/runner";
 import type { NodeBase } from "@blokjs/shared";
-import ChainInit from "./nodes/chain-init/index";
-import ChainVerify from "./nodes/chain-verify/index";
 import ExampleNodes from "./nodes/examples/index";
-import RuntimeBridge from "./nodes/runtime-bridge/index";
-
-const nodes: {
-	[key: string]: NodeBase;
-} = {
-	"@blokjs/api-call": ApiCall,
-	"@blokjs/if-else": IfElse,
-	"chain-init": ChainInit,
-	"chain-verify": ChainVerify,
-	"runtime-bridge": RuntimeBridge,
-	...ExampleNodes,
-};
+
+// Published nodes (npm) + the example bundle are registered explicitly below.
+// Your OWN nodes under 'nodes/<name>/index.ts' are AUTO-DISCOVERED and registered
+// by their defineNode({ name }) — you never edit this file to add a node.
+const here = dirname(fileURLToPath(import.meta.url));
+const local = await discoverNodes(join(here, "nodes"));
+
+const explicit: NodeBase[] = [ApiCall, IfElse, ...(Object.values(ExampleNodes) as NodeBase[])];
+
+// Map keys are cosmetic — the runner registers each node under its own node.name
+// (the canonical 'use:' ref). Duplicate refs throw at startup.
+const nodes: { [key: string]: NodeBase } = {};
+for (const node of [...explicit, ...local]) {
+	nodes[(node as { name: string }).name] = node;
+}
 
 export default nodes;
 `;
@@ -349,7 +353,52 @@ Blok is a **multi-trigger, multi-runtime workflow framework**. A workflow is a d
 The 9 trigger types: \`http\`, \`worker\`, \`cron\`, \`pubsub\`, \`sse\`, \`websocket\`, \`webhook\`, \`mcp\`, \`grpc\`.
 The 8 runtimes: \`typescript\` (in-process), \`go\`, \`rust\`, \`java\`, \`csharp\`, \`php\`, \`ruby\`, \`python3\`.
 
-The canonical workflow form is \`workflow({ name, version, trigger, steps })\` from \`@blokjs/helper\`. The same shape works for all 9 triggers — only the \`trigger:\` block changes.
+The canonical TypeScript form is the **typed-handle DSL** from \`@blokjs/core\`: \`workflow(name, { version, trigger }, (entry) => { ... })\`, where each \`step()\` returns a typed handle you reference directly — **no \`$\`, no \`js/\`, no raw \`ctx\` strings.** The object-style \`workflow({ name, version, trigger, steps: [...] })\` from \`@blokjs/helper\` and JSON workflows are equivalent (all three compile to the same IR) and remain fully supported. The same shape works for all 9 triggers — only the \`trigger:\` block changes.
+
+---
+
+## 0. THE TYPED-HANDLE DSL (\`@blokjs/core\`) — preferred for TypeScript
+
+\`\`\`ts
+import { workflow, step, branch, forEach, switchOn, tryCatch, http, tpl, gt } from "@blokjs/core";
+
+export default workflow("order-intake", { version: "1.0.0", trigger: http.post("/orders") }, (req) => {
+  // step(id, node, inputs) → a TYPED handle shaped like the node's output.
+  const order = step("validate", validateOrder, { qty: req.body.qty });
+
+  // Reference a handle field anywhere downstream — it records a ref the runner resolves.
+  step("summary", summarize, { line: tpl\`order of \${order.qty} item(s)\` });
+
+  // Control flow: a comparator (gt/eq/lt/...) builds the condition; arms are callbacks.
+  branch("lane", gt(order.qty, 10), {
+    then: () => { step("bulk", routeOrder, { lane: "bulk" }); },
+    else: () => { step("standard", routeOrder, { lane: "standard" }); },
+  });
+});
+\`\`\`
+
+**Trigger config:** \`http.{get,post,put,delete,patch,any}(path?, opts?)\` for HTTP (omit \`path\` for file-based routing). For any other trigger pass the raw block as \`trigger:\` — e.g. \`{ worker: { queue: "jobs" } }\`, \`{ cron: { schedule: "0 2 * * *" } }\`, \`{ webhook: { source: "stripe" } }\`.
+
+**The entry handle** (the callback's argument) is the trigger payload — typed and conventionally named per trigger: \`http\`→\`req\`, \`webhook\`→\`event\`, \`cron\`→\`tick\`, \`worker\`→\`job\`, \`pubsub\`→\`msg\`, \`grpc\`→\`rpc\` (others get a loose handle). Read \`req.body\`, \`req.params.id\`, \`req.query.q\`, \`req.headers["x-…"]\`.
+
+**Handles & persistence:**
+- \`const h = step("id", node, inputs)\` — every step auto-persists to \`ctx.state["id"]\` on success; \`h\` / \`h.field\` is how you reference it later (never \`$.state.id\`).
+- 4th arg \`opts\`: \`{ as: "name" }\` roots the handle at \`state["name"]\`; \`{ spread: true }\` flattens \`result.data\` into state (mutually exclusive with \`as\`); \`{ ephemeral: true }\` skips persistence (handle then unreadable downstream); also \`idempotencyKey\`, \`retry\`, \`maxDuration\`, \`type: "runtime.<lang>"\`.
+- \`tpl\`…\${h.field}…\`\` builds a string with embedded handle refs.
+- Comparators (typed): \`eq, ne, gt, gte, lt, lte, not\`. A bare boolean handle is a truthiness check.
+- \`defineNode\` is re-exported from \`@blokjs/core\` — author nodes exactly as before; just RETURN output (never write \`ctx.state\`/\`ctx.vars\`).
+
+**Control-flow primitives** (all from \`@blokjs/core\`):
+- \`branch(id, cond, { then: () => {…}, else?: () => {…} })\` — \`cond\` is a comparator or a boolean handle.
+- \`forEach(iterable, (item, index) => { step(…) }, { as?, mode?, concurrency? })\` — \`iterable\` is a handle; \`item\`/\`index\` are per-iteration handles; \`mode: "parallel"\` bounds with \`concurrency\` (default 10).
+- \`switchOn(discriminant, { cases: [{ when: "push", do: () => {…} }], default?: () => {…} }, { id })\` — \`when\` labels are STATIC literals (a handle never matches).
+- \`tryCatch(id, { try: () => {…}, catch: (error) => { step("log", logger, { msg: error.message }); }, finally?: () => {…} })\` — \`error\` is a typed handle (\`.message\`/\`.name\`/\`.stack\`/\`.code\`/\`.stepId\`).
+
+**The four footguns** (full detail: \`docs/d/primitives/handles-and-footguns.mdx\`):
+1. **Arm-scoped handles don't escape their arm.** A handle minted inside a \`branch\`/\`switchOn\`/\`tryCatch\`/\`forEach\` arm is unreadable outside it. Return a value from the control-flow step, or have both arms write one \`as:\` key.
+2. **Ephemeral handles are unreadable.** Reading an \`{ ephemeral: true }\` step's handle resolves to \`undefined\`.
+3. **Never reuse a step \`id\`** — including across mutually-exclusive arms. Ids are a flat per-workflow map; the runner throws at load time. Use \`as:\` when two arms must write the same downstream key.
+4. **Never name a \`forEach\` \`as:\`/\`asIndex\` after an existing step id** (or another loop's \`as\`) — they share \`ctx.state\`; the runner throws at load time.
 
 ---
 
@@ -858,7 +907,7 @@ Process-global middleware: \`WorkflowRegistry.getInstance().setGlobalMiddleware(
 Always \`export default defineNode(...)\`. Never class-based \`BlokService\`. Zod input/output are mandatory.
 
 \`\`\`ts
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 import { z } from "zod";
 
 export default defineNode({
@@ -1211,12 +1260,12 @@ Plus the cross-runtime rules: **the wrong input source** (typed sidecar nodes re
 
 ## 8. TESTING
 
-Use the \`@blokjs/runner\` testing utilities with Vitest.
+Use the \`@blokjs/core/testing\` utilities with Vitest (same package you author against).
 
 **Unit-test a node** with \`NodeTestHarness\`:
 
 \`\`\`ts
-import { NodeTestHarness } from "@blokjs/runner";
+import { NodeTestHarness } from "@blokjs/core/testing";
 import myNode from "../src/nodes/my-node";
 
 const harness = new NodeTestHarness(myNode);
@@ -1228,7 +1277,7 @@ harness.assertOutput(result, { user: { id: "abc-123" } });
 **Integration-test a workflow** with \`WorkflowTestRunner\`:
 
 \`\`\`ts
-import { WorkflowTestRunner } from "@blokjs/runner";
+import { WorkflowTestRunner } from "@blokjs/core/testing";
 
 const runner = new WorkflowTestRunner({ verbose: true, mockAllNodes: true });
 runner.registerNode("validate", ValidateNode);
@@ -1334,7 +1383,7 @@ Per-step reliability lives on the step: \`idempotencyKey\` (cache by \`(workflow
 Always \`export default defineNode(...)\` (TS) — never class-based \`BlokService\`. Zod input/output are mandatory. Never write \`ctx.state\` from a node — return your output and let the runner persist it (use \`ctx.publish(name, value)\` for a true side-channel). No \`any\` types — use \`z.unknown()\`.
 
 \`\`\`typescript
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 import { z } from "zod";
 
 export default defineNode({
@@ -1388,7 +1437,21 @@ Registration is **manual** in non-TS runtimes — importing the module runs the
 
 ## 4. Generating Workflows
 
-Canonical form: \`workflow({ name, version, trigger, steps })\` from \`@blokjs/helper\` — one object literal, no chained builder, no separate \`nodes{}\` map. \`name\` ≥ 3 chars, \`version\` ≥ 5 chars (semver). Reference earlier outputs with \`$.state.<id>\` / \`$.req.body\`. Use \`branch\`, \`switchOn\`, \`forEach\`, \`loop\`, \`tryCatch\` (all from \`@blokjs/helper\`) for control flow.
+**Preferred (TypeScript): the typed-handle DSL from \`@blokjs/core\`.** \`workflow(name, { version, trigger }, (entry) => { ... })\` — each \`step(id, node, inputs)\` returns a typed handle you reference directly; no \`$\`, no \`js/\`, no raw \`ctx\` strings. \`http.{get,post,…}(path?)\` builds the trigger; other triggers pass the raw block (\`{ worker: { queue } }\`, \`{ cron: { schedule } }\`, …). Entry name per trigger: \`http\`→\`req\`, \`worker\`→\`job\`, \`cron\`→\`tick\`, \`webhook\`→\`event\`, \`pubsub\`→\`msg\`, \`grpc\`→\`rpc\`.
+
+\`\`\`typescript
+import { workflow, step, branch, gt, http } from "@blokjs/core";
+
+export default workflow("Process Order", { version: "1.0.0", trigger: http.post("/orders") }, (req) => {
+  const order = step("validate", orderValidator, { order: req.body });   // typed handle
+  step("save", orderStore, { data: order });                            // reference it directly
+  branch("big", gt(order.total, 100), { then: () => { step("vip", flagVip, { id: order.id }); } });
+});
+\`\`\`
+
+Control flow (all from \`@blokjs/core\`): \`branch(id, cond, {then,else?})\`, \`forEach(iterable, (item,i)=>{}, {as?,mode?})\`, \`switchOn(disc, {cases:[{when,do}],default?}, {id})\`, \`tryCatch(id, {try,catch:(err)=>{},finally?})\`; comparators \`eq/ne/gt/gte/lt/lte/not\`; \`tpl\`…\${h.x}…\`\` for strings. The **four footguns**: arm-scoped handles don't escape their arm; ephemeral handles read \`undefined\`; never reuse a step \`id\`; never name a \`forEach\` \`as:\` after an existing id. See \`docs/d/primitives/handles-and-footguns.mdx\`.
+
+**Equivalent object-style form** (\`@blokjs/helper\`, also valid; JSON mirrors it): one object literal, \`steps: [...]\`, reference outputs with \`$.state.<id>\` / \`$.req.body\`.
 
 \`\`\`typescript
 import { workflow, $ } from "@blokjs/helper";
@@ -1461,7 +1524,7 @@ branch({ id: "route",
 - Do NOT generate class-based \`BlokService\` nodes or use \`any\` types — always \`defineNode()\` (TS) / \`@node\` (Python) with Zod/Pydantic schemas.
 - Do NOT use ESLint/Prettier — this project uses Biome. Do NOT edit auto-generated files in \`.blok/runtimes/\`.
 `;
-const function_first_node_file = `import { defineNode } from "@blokjs/runner";
+const function_first_node_file = `import { defineNode } from "@blokjs/core";
 import { z } from "zod";
 
 /**
@@ -1486,13 +1549,13 @@ export default defineNode({
 	// Execute function - type-safe with inferred types from Zod schemas
 	async execute(ctx, input) {
 		// Your business logic here
-		// - ctx.vars: Access workflow variables
 		// - ctx.request: Access HTTP request data
 		// - ctx.logger: Log messages
 		// - ctx.env: Access environment variables
-
-		// Example: Store data for downstream nodes
-		ctx.vars["processed-message"] = input.message;
+		//
+		// Just RETURN your output — the runner auto-persists it to
+		// ctx.state["{{NODE_NAME}}"], readable from any later step's handle.
+		// Do NOT write to ctx.state / ctx.vars inside a node.
 
 		// Return type-safe output (validated automatically)
 		return {

package/dist/commands/generate/WorkflowGenerator.js

@@ -101,11 +101,11 @@ export default class WorkflowGenerator {
             "```",
             "",
             "Please fix these errors and regenerate the workflow JSON. Common fixes:",
-            "- Ensure every step name has a matching entry in the nodes object",
+            "- Ensure every step has a unique `id` and a `use` (or a `branch`) — inputs live inline; there is NO `nodes` map",
             "- Ensure the trigger has exactly one trigger type with valid configuration",
-            "- Ensure condition expressions use ctx.* properties",
-            "- Ensure all conditional branches have name, node, and type fields",
-            "- Add an else branch to conditional routing for error handling",
+            "- Ensure branch `when` is a raw `ctx.*` expression (never `js/` or `$.`)",
+            "- Reference earlier outputs with `$.state.<id>` and request data with `$.req.*`",
+            "- Use a single step with `branch: { when, then, else }` for conditionals (not a `conditions` array)",
         ].join("\n");
         return feedback;
     }

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

@@ -70,8 +70,8 @@ describe("WorkflowGenerator", () => {
         });
         it("should include common fix suggestions", () => {
             const result = createFeedback("Test", "{}", ["Missing node entry"]);
-            expect(result).toContain("step name has a matching entry");
-            expect(result).toContain("else branch");
+            expect(result).toContain("unique `id`");
+            expect(result).toContain("branch: { when, then, else }");
         });
     });
 });

package/dist/commands/generate/prompts/create-fn-node.system.js

@@ -9,7 +9,7 @@ What to return:
   1. Proper imports:
      * \`z\` from \`zod\`
      * \`Context\` from \`@blokjs/shared\`
-     * \`defineNode\` from \`@blokjs/runner\`
+     * \`defineNode\` from \`@blokjs/core\`
   2. A clear and structured \`input\` schema using Zod (z.object with proper types).
   3. A matching \`output\` schema using Zod.
   4. A single exported node instance created via \`defineNode\` with:
@@ -26,11 +26,11 @@ Constraints:
 * The Zod \`output\` schema must fully describe the object returned by \`execute\`.
 * Inside \`execute(ctx, input)\`:
   * Use the strongly-typed \`input\`, which is automatically inferred from the Zod schema.
-  * Use \`ctx\` to access request data, configuration, and cross-node state when needed:
+  * Use \`ctx\` to access request data, configuration, and logging when needed:
     * \`ctx.request.body\`, \`ctx.request.query\`, \`ctx.request.params\` for HTTP data
-    * \`ctx.vars\` for reading/writing values shared between nodes
     * \`ctx.logger\` for logging
     * \`ctx.env\` for environment variables
+  * Do **not** write to \`ctx.state\`/\`ctx.vars\` from a node — just RETURN your output; the runner auto-persists it to \`ctx.state[<step-id>]\` for downstream steps. Upstream values arrive as \`input.*\` (mapped in the workflow), not by reading \`ctx.vars\`.
   * Do **not** construct or return \`BlokResponse\` here; just return a plain object matching the output schema. The wrapper created by \`defineNode\` will call \`setSuccess\` / \`setError\` and handle \`GlobalError\`.
 * On validation errors or runtime errors, you do NOT manually throw \`GlobalError\`; throw/rethrow normal errors. The \`defineNode\` wrapper will catch them and map them to \`GlobalError\` consistently with proper error codes:
   * Zod validation errors → 400 Bad Request
@@ -52,7 +52,7 @@ Real-World Examples to Guide You:
 \`\`\`typescript
 import type { Context } from "@blokjs/shared";
 import { z } from "zod";
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 
 export default defineNode({
 	name: "api-call",
@@ -102,10 +102,6 @@ export default defineNode({
 
 		ctx.logger.log(\`Request completed in \${duration.toFixed(2)}ms with status \${response.status}\`);
 
-		if (ctx.vars) {
-			ctx.vars["api-response"] = { status: response.status, data };
-		}
-
 		return {
 			status: response.status,
 			statusText: response.statusText,
@@ -122,7 +118,7 @@ export default defineNode({
 \`\`\`typescript
 import type { Context } from "@blokjs/shared";
 import { z } from "zod";
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 
 export default defineNode({
 	name: "fetch-user",
@@ -149,11 +145,8 @@ export default defineNode({
 		// Simulate database fetch
 		const user = await fetchUserFromDatabase(input.userId, input.includeMetadata);
 
-		// Store in context for downstream nodes
-		if (ctx.vars) {
-			ctx.vars["current-user"] = user;
-		}
-
+		// Just return — the runner persists this to ctx.state["fetch-user"]
+		// for any downstream step that maps it in as an input.
 		return { user };
 	},
 });
@@ -176,7 +169,7 @@ Template to follow (adapt and fill based on the user's request):
 
 import type { Context } from "@blokjs/shared";
 import { z } from "zod";
-import { defineNode } from "@blokjs/runner";
+import { defineNode } from "@blokjs/core";
 
 /**
  * [Brief description of what this node does]
@@ -210,11 +203,11 @@ export default defineNode({
 		//
 		// Common patterns:
 		// - Read HTTP params: const id = ctx.request.params.id;
-		// - Read previous node output: const prev = ctx.vars["previous-node-key"];
-		// - Write for future nodes: ctx.vars["this-node-key"] = someValue;
+		// - Read upstream values via input.* (mapped from prior steps in the workflow) — NOT ctx.vars
 		// - Use input.* fields that match the input schema (TypeScript infers the type automatically)
 		// - Log messages: ctx.logger.log("Processing request");
 		// - Access environment: const apiKey = ctx.env.API_KEY;
+		// - Do NOT write ctx.state/ctx.vars here — just return; the runner persists your output.
 
 		// TODO: Implement business logic here