blokctl 1.1.0 → 1.3.0

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

@@ -1,6 +1,7 @@
 const node_file = `import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import ApiCall from "@blokjs/api-call";
+import { HELPER_NODES } from "@blokjs/helpers";
 import IfElse from "@blokjs/if-else";
 import { discoverNodes } from "@blokjs/runner";
 import type { NodeBase } from "@blokjs/shared";
@@ -12,7 +13,12 @@ import ExampleNodes from "./nodes/examples/index";
 const here = dirname(fileURLToPath(import.meta.url));
 const local = await discoverNodes(join(here, "nodes"));
 
-const explicit: NodeBase[] = [ApiCall, IfElse, ...(Object.values(ExampleNodes) as NodeBase[])];
+const explicit: NodeBase[] = [
+	ApiCall,
+	IfElse,
+	...(Object.values(HELPER_NODES) as unknown as NodeBase[]),
+	...(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.
@@ -69,31 +75,28 @@ Examples:
 7- Webhook router: POST /webhooks/{stripe,github,linear} with signed bodies — set the matching *_WEBHOOK_SECRET env vars (needs --triggers webhook)
 8- LLM agent w/ tool calls: open http://localhost:4000/agent — model picks between get_weather and calculate tools (needs OPENROUTER_API_KEY + Redis)
 9- Worker fan-out: POST /fanout/jobs with body '{items:[...], tenantId?:"..."}' to enqueue N worker jobs (needs --triggers worker; BLOK_WORKER_ADAPTER=in-memory works single-process)
-10- Trigger references (NOT http): workflows/json/{cron-heartbeat,pubsub-on-order,websocket-echo}.json demonstrate the cron, pubsub, and websocket triggers — read AGENTS.md "Choosing a trigger" to pick the right one by intent instead of defaulting to HTTP.
+10- Trigger references (NOT http): workflows/json/{cron-heartbeat,pubsub-on-order}.json demonstrate the cron and pubsub triggers; src/workflows/websocket/events/echo-demo.ts demonstrates websocket — read AGENTS.md "Choosing a trigger" to pick the right one by intent instead of defaulting to HTTP.
 
 For more documentation, visit src/nodes/examples/README.md. The first three examples require a PostgreSQL database to function.
 `;
-const workflow_template = `
-{
-	"name": "My Workflow",
-	"description": "What this workflow does",
-	"version": "1.0.0",
-	"trigger": {
-		"http": {
-			"method": "GET",
-			"accept": "application/json"
-		}
+const workflow_template = `import { http, node, step, workflow } from "@blokjs/core";
+
+/**
+ * {{WORKFLOW_NAME}}
+ *
+ * Add steps with step("id", node, inputs). Read a step's output downstream via
+ * the handle it returns (const user = step(...); ... user.name). Control flow:
+ * branch / forEach / switchOn / tryCatch — all from @blokjs/core.
+ */
+export default workflow(
+	"{{WORKFLOW_NAME}}",
+	{ version: "1.0.0", trigger: http.get("{{WORKFLOW_PATH}}") },
+	(req) => {
+		// Echo the request body back. @blokjs/respond writes the HTTP response,
+		// so mark it ephemeral (no state slot needed).
+		step("echo", node("@blokjs/respond"), { body: req.body }, { ephemeral: true });
 	},
-	"steps": [
-		{
-			"id": "echo",
-			"use": "@blokjs/respond",
-			"inputs": {
-				"body": "$.req.body"
-			}
-		}
-	]
-}
+);
 `;
 const supervisord_nodejs = `
 [supervisord]
@@ -438,7 +441,7 @@ Regardless of kind, every trigger populates \`ctx.request.{body,headers,params,q
 
 ## 2. THE 9 TRIGGERS
 
-Each trigger below: one-line purpose, USE-WHEN / DON'T, config shape, and a canonical \`workflow({...})\` example.
+Each trigger below: one-line purpose, USE-WHEN / DON'T, config shape, and a canonical typed-handle \`workflow(name, { trigger }, (entry) => { ... })\` example.
 
 ### 2.1 HTTP — \`trigger: { http: {...} }\`
 
@@ -458,16 +461,11 @@ trigger: { http: {
 \`\`\`
 
 \`\`\`ts
-import { workflow, $ } from "@blokjs/helper";
+import { http, node, step, tpl, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "Get User", version: "1.0.0",
-  trigger: { http: { method: "GET", path: "/users/:id" } },
-  steps: [
-    { id: "lookup", use: "@blokjs/api-call",
-      inputs: { url: "js/\`https://internal/users/\${ctx.request.params.id}\`" } },
-    { id: "respond", use: "@blokjs/respond", inputs: { body: $.state.lookup }, ephemeral: true },
-  ],
+export default workflow("Get User", { version: "1.0.0", trigger: http.get("/users/:id") }, (req) => {
+  const user = step("lookup", node("@blokjs/api-call"), { url: tpl\`https://internal/users/\${req.params.id}\` });
+  step("respond", node("@blokjs/respond"), { body: user }, { ephemeral: true });
 });
 \`\`\`
 
@@ -491,15 +489,10 @@ trigger: { worker: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
+import { node, step, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "Process Background Job", version: "1.0.0",
-  trigger: { worker: { queue: "background-jobs" } },
-  steps: [
-    { id: "process-job", use: "@blokjs/api-call", type: "module",
-      inputs: { url: "https://example.com/process", method: "POST", body: "js/ctx.request.body" } },
-  ],
+export default workflow("Process Background Job", { version: "1.0.0", trigger: { worker: { queue: "background-jobs" } } }, (job) => {
+  step("process-job", node("@blokjs/api-call"), { url: "https://example.com/process", method: "POST", body: job.body });
 });
 \`\`\`
 
@@ -521,15 +514,10 @@ trigger: { cron: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
+import { node, step, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "Daily Cleanup", version: "1.0.0",
-  trigger: { cron: { schedule: "0 2 * * *", timezone: "America/New_York" } },
-  steps: [
-    { id: "purge-stale", use: "@blokjs/api-call",
-      inputs: { url: "https://api.example.com/cleanup", method: "POST" } },
-  ],
+export default workflow("Daily Cleanup", { version: "1.0.0", trigger: { cron: { schedule: "0 2 * * *", timezone: "America/New_York" } } }, () => {
+  step("purge-stale", node("@blokjs/api-call"), { url: "https://api.example.com/cleanup", method: "POST" });
 });
 \`\`\`
 
@@ -556,16 +544,12 @@ trigger: { pubsub: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
+import { node, step, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "On Order Placed", version: "1.0.0",
-  trigger: { pubsub: { provider: "gcp", topic: "orders.placed", subscription: "fulfillment-svc" } },
-  steps: [
-    { id: "fulfill", use: "@blokjs/api-call",
-      idempotencyKey: "js/ctx.request.params.messageId",   // dedup redeliveries
-      inputs: { url: "https://fulfillment.internal/api/orders", method: "POST", body: "js/ctx.request.body" } },
-  ],
+export default workflow("On Order Placed", { version: "1.0.0", trigger: { pubsub: { provider: "gcp", topic: "orders.placed", subscription: "fulfillment-svc" } } }, (msg) => {
+  step("fulfill", node("@blokjs/api-call"),
+    { url: "https://fulfillment.internal/api/orders", method: "POST", body: msg.body },
+    { idempotencyKey: msg.params.messageId });   // dedup redeliveries
 });
 \`\`\`
 
@@ -590,15 +574,11 @@ trigger: { sse: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
+import { node, step, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "Clock Stream", version: "1.0.0",
-  trigger: { sse: { path: "/sse/clock", heartbeatInterval: 15000 } },
-  steps: [
-    { id: "sub", use: "@blokjs/sse-subscribe", inputs: { channels: ["clock"] } },
-    { id: "stream", use: "@blokjs/sse-stream", inputs: { source: "js/ctx.state.sub" } },
-  ],
+export default workflow("Clock Stream", { version: "1.0.0", trigger: { sse: { path: "/sse/clock", heartbeatInterval: 15000 } } }, () => {
+  const sub = step("sub", node("@blokjs/sse-subscribe"), { channels: ["clock"] });
+  step("stream", node("@blokjs/sse-stream"), { source: sub });
 });
 \`\`\`
 
@@ -623,15 +603,11 @@ trigger: { websocket: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
+import { js, node, step, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "WS Echo", version: "1.0.0",
-  trigger: { websocket: { path: "/ws/echo", events: ["message", "open", "close"] } },
-  steps: [
-    { id: "reply", use: "@blokjs/ws-reply",
-      inputs: { message: "js/({ echo: ctx.request.body, at: Date.now() })" } },
-  ],
+export default workflow("WS Echo", { version: "1.0.0", trigger: { websocket: { path: "/ws/echo", events: ["message", "open", "close"] } } }, (conn) => {
+  // \`js\` is the escape hatch for a non-structural expression (Date.now()).
+  step("reply", node("@blokjs/ws-reply"), { message: js\`({ echo: \${conn.body}, at: Date.now() })\` });
 });
 \`\`\`
 
@@ -662,18 +638,14 @@ trigger: { webhook: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
-
-export default workflow({
-  name: "Stripe Webhook", version: "1.0.0",
-  trigger: { webhook: {
-    provider: "stripe", namespace: "stripe",
-    secretEnv: "STRIPE_WEBHOOK_SECRET", idempotencyKey: "js/ctx.request.body.id",
-  }},
-  steps: [
-    { id: "dispatch", subworkflow: "js/ctx.request.body.type",   // "invoice.paid" → "stripe.invoice.paid"
-      inputs: { stripeEvent: "js/ctx.request.body" } },
-  ],
+import { subworkflow, workflow } from "@blokjs/core";
+
+export default workflow("Stripe Webhook", { version: "1.0.0", trigger: { webhook: {
+  provider: "stripe", namespace: "stripe",
+  secretEnv: "STRIPE_WEBHOOK_SECRET", idempotencyKey: "js/ctx.request.body.id",
+} } }, (event) => {
+  // polymorphic dispatch: "invoice.paid" → "stripe.invoice.paid" (namespace prefix from the trigger)
+  subworkflow("dispatch", event.body.type, { stripeEvent: event.body });
 });
 \`\`\`
 
@@ -700,15 +672,16 @@ trigger: { mcp: {
 **Requires a workflow-level \`input:\` Zod schema** — that becomes the tool's \`inputSchema\`:
 
 \`\`\`ts
-import { workflow, $ } from "@blokjs/helper";
+import { node, step, workflow } from "@blokjs/core";
 import { z } from "zod";
 
-export default workflow({
-  name: "search_code", version: "1.0.0",
+export default workflow("search_code", {
+  version: "1.0.0",
   input: z.object({ query: z.string(), limit: z.number().optional() }),  // → tool inputSchema
   trigger: { mcp: { path: "/mcp", serverName: "my-platform",
                     tool: { description: "Full-text search the indexed code" } } },
-  steps: [ { id: "search", use: "@my/search", inputs: { query: $.req.body.query } } ],
+}, (call) => {
+  step("search", node("@my/search"), { query: call.body.query });
 });
 \`\`\`
 
@@ -740,27 +713,22 @@ trigger: { grpc: {
 \`\`\`
 
 \`\`\`ts
-import { workflow } from "@blokjs/helper";
+import { node, step, tpl, workflow } from "@blokjs/core";
 
-export default workflow({
-  name: "GetUser", version: "1.0.0",
-  trigger: { grpc: { service: "UserService", method: "GetUser", proto: "users.proto" } },
-  steps: [
-    { id: "lookup", use: "@blokjs/api-call",
-      inputs: { url: "js/\`https://internal/users/\${ctx.request.body.userId}\`", method: "GET" } },
-  ],
+export default workflow("GetUser", { version: "1.0.0", trigger: { grpc: { service: "UserService", method: "GetUser", proto: "users.proto" } } }, (rpc) => {
+  step("lookup", node("@blokjs/api-call"), { url: tpl\`https://internal/users/\${rpc.body.userId}\`, method: "GET" });
 });
 \`\`\`
 
-The request decodes into \`ctx.request.body\`; the final step output becomes the gRPC reply. Streaming RPCs use \`@blokjs/grpc-stream\`.
+The request decodes into \`ctx.request.body\`; the final step output becomes the gRPC reply. (Server-streaming RPCs are not yet supported by the inbound trigger.)
 
 > **\`trigger.queue\` is DEAD** — it has a schema but no runtime and throws at workflow construction. Use \`worker\`. **\`manual\`** has no listener (invoked programmatically only — tests / sub-workflows); not for normal authoring.
 
 ---
 
-## 3. AUTHORING WORKFLOWS (v2 DSL)
+## 3. AUTHORING WORKFLOWS — object-style & JSON (legacy; see §0 for the canonical typed-handle DSL)
 
-Import from \`@blokjs/helper\`: \`{ workflow, $, branch, switchOn, forEach, loop, tryCatch }\`. The default export is \`workflow({...})\` — a single object literal, no chaining, no separate \`nodes{}\` map.
+§0 covers the canonical typed-handle DSL (\`workflow(name, { trigger }, (entry) => { ... })\`). This section documents the **equivalent object-style form** (\`@blokjs/helper\`, one \`workflow({...})\` object literal with \`$\` reads) and JSON — both still fully supported for migrating and maintaining existing workflows; all three compile to the same IR. The persistence knobs and control-flow semantics below apply to every form.
 
 \`\`\`ts
 import { workflow, $ } from "@blokjs/helper";
@@ -890,10 +858,14 @@ For HTTP, \`ttl\` requires \`delay\`. Debounce modes: \`trailing\` (default —
    \`\`\`ts
    trigger: { http: { method: "GET", middleware: ["auth-check", "request-id"] } }
    \`\`\`
-2. *Defining a middleware workflow* — \`workflow({ middleware: true })\`. \`trigger\` becomes optional; it gets no public route and is referenced by \`name\`:
+2. *Defining a middleware workflow* — \`workflow(name, { middleware: true }, cb)\`. \`trigger\` becomes optional; it gets no public route and is referenced by \`name\`:
    \`\`\`ts
-   export default workflow({ name: "auth-check", version: "1.0.0", middleware: true,
-     steps: [ /* sets ctx.state.identity; may stop:true to short-circuit */ ] });
+   import { node, step, workflow } from "@blokjs/core";
+
+   export default workflow("auth-check", { version: "1.0.0", middleware: true }, () => {
+     // populate ctx.state.identity; a step may return stop:true to short-circuit the chain
+     step("identity", node("@my/verify-auth"), {});
+   });
    \`\`\`
 
 Process-global middleware: \`WorkflowRegistry.getInstance().setGlobalMiddleware([...])\` or \`BLOK_GLOBAL_MIDDLEWARE=a,b\`.
@@ -1294,9 +1266,9 @@ expect(result.success).toBe(true);
 **Do:**
 - Read \`.blok/config.json\` and existing \`src/workflows/\` to learn which triggers + runtimes this project uses; author for those.
 - Start every workflow from the **trigger decision table** in §1, not from HTTP.
-- Use \`workflow({ name, version, trigger, steps })\` from \`@blokjs/helper\`.
+- Author with the typed-handle DSL — \`workflow(name, { version, trigger }, (entry) => { step("id", node("@pkg"), inputs) })\` from \`@blokjs/core\` (§0). Object-style \`workflow({...})\` and JSON stay valid for legacy/migration.
 - Use the typed node contract in every runtime (\`defineNode\` / \`DefineNode\` / \`TypedNode\` / \`@node\`).
-- Reference cross-step outputs with \`$.state.<id>\`; use \`as:\`/\`spread:\`/\`ephemeral:\` to shape persistence.
+- Reference cross-step outputs via the handle \`step()\` returns (not \`$.state.<id>\`); use the 4th-arg \`as:\`/\`spread:\`/\`ephemeral:\` knobs to shape persistence.
 - Set \`type: "runtime.<lang>"\` on every sidecar step and register the node by name.
 
 **Do NOT:**

package/dist/commands/create/workflow.js

@@ -59,7 +59,7 @@ export async function createWorkflow(opts, currentPath = false) {
             const nodeProjectDirExists = fsExtra.existsSync(currentDir);
             if (!nodeProjectDirExists)
                 throw new Error("ops1");
-            const currentWorkflowsDir = `${dirPath}/workflows/json`;
+            const currentWorkflowsDir = `${dirPath}/workflows`;
             if (!skipPrompts) {
                 fsExtra.ensureDirSync(currentWorkflowsDir);
             }
@@ -68,10 +68,10 @@ export async function createWorkflow(opts, currentPath = false) {
                 if (!workflowDirExists)
                     throw new Error("ops1");
             }
-            dirPath = path.join(currentWorkflowsDir, `${workflowName.replaceAll(" ", "-").toLowerCase()}.json`);
+            dirPath = path.join(currentWorkflowsDir, `${workflowName.replaceAll(" ", "-").toLowerCase()}.ts`);
         }
         else {
-            dirPath = path.join(dirPath, `${workflowName.replaceAll(" ", "-").toLowerCase()}.json`);
+            dirPath = path.join(dirPath, `${workflowName.replaceAll(" ", "-").toLowerCase()}.ts`);
         }
         if (!skipPrompts)
             s.message("Creating workflow...");
@@ -80,9 +80,11 @@ export async function createWorkflow(opts, currentPath = false) {
             if (workflowDirExists)
                 throw new Error("ops2");
         }
-        const workflow_json = JSON.parse(workflow_template);
-        workflow_json.name = workflowName;
-        fsExtra.writeFileSync(dirPath, JSON.stringify(workflow_json, null, 2));
+        const slug = workflowName.replaceAll(" ", "-").toLowerCase();
+        const workflow_ts = workflow_template
+            .replaceAll("{{WORKFLOW_NAME}}", workflowName)
+            .replaceAll("{{WORKFLOW_PATH}}", `/${slug}`);
+        fsExtra.writeFileSync(dirPath, workflow_ts);
         if (!skipPrompts)
             s.stop(`Node "${workflowName}" created successfully.`);
         if (!currentPath)

package/dist/commands/dev/index.js

@@ -4,8 +4,9 @@ import path from "node:path";
 import util from "node:util";
 import fsExtra from "fs-extra";
 import { waitForGrpcPort } from "../../services/health-probe.js";
-import { detectRr } from "../../services/runtime-detector.js";
+import { detectJava, detectRr } from "../../services/runtime-detector.js";
 import { generateCSharpNodeRegistry, generateGoNodeRegistry, generateJavaNodeRegistry, generateRustNodeRegistry, readProjectConfig, validateProjectRuntimes, } from "../../services/runtime-setup.js";
+import { regenRuntimeStubs } from "../nodes/syncNodes.js";
 const exec = util.promisify(child_process.exec);
 const runningProcesses = [];
 function spawnProcess(cmd, args, name, currentPath, cwd, env) {
@@ -42,6 +43,25 @@ function killAllGroups(signal) {
         }
     }
 }
+async function regenStubsWhenReady(baseUrl, outDir, deadlineMs = 60_000) {
+    const endpoint = `${baseUrl}/__blok/nodes`;
+    const start = Date.now();
+    while (Date.now() - start < deadlineMs) {
+        try {
+            const res = await fetch(endpoint);
+            if (res.ok) {
+                const count = await regenRuntimeStubs(baseUrl, outDir);
+                if (count > 0)
+                    console.log(`Regenerated ${count} runtime stub file(s) → ${path.relative(process.cwd(), outDir)}`);
+                return;
+            }
+        }
+        catch {
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    console.log(`  Warning: stub regen skipped — ${endpoint} did not respond within ${deadlineMs / 1000}s.`);
+}
 export async function devProject(opts) {
     const currentPath = process.cwd();
     console.log("Starting the development server (transport=grpc)...");
@@ -86,6 +106,12 @@ export async function devProject(opts) {
                     bootCmd = `${rrBin}${bootCmd.slice(2)}`;
                 }
             }
+            if (rt.kind === "java" && bootCmd.startsWith("java ")) {
+                const javaBin = detectJava();
+                if (javaBin && javaBin !== "java") {
+                    bootCmd = `${javaBin}${bootCmd.slice(4)}`;
+                }
+            }
             const cmdParts = bootCmd.split(" ");
             const cmd = cmdParts[0];
             const args = cmdParts.slice(1);
@@ -178,6 +204,12 @@ export async function devProject(opts) {
             if (brokerConsumerKinds.has(trigger.kind)) {
                 console.log(`  ${trigger.label}: consumes from broker (no HTTP endpoint)`);
             }
+            else if (trigger.kind === "cron") {
+                console.log(`  ${trigger.label}: scheduled (no HTTP endpoint)`);
+            }
+            else if (trigger.kind === "grpc") {
+                console.log(`  ${trigger.label}: gRPC 127.0.0.1:${trigger.port}`);
+            }
             else {
                 console.log(`  ${trigger.label}: http://localhost:${trigger.port}/health-check`);
             }
@@ -233,6 +265,12 @@ export async function devProject(opts) {
     else {
         spawnProcess("bun", ["--watch", "run", "src/index.ts"], "Blok Runner", currentPath, undefined, triggerEnv);
     }
+    const httpTrigger = config?.triggers?.http;
+    if (httpTrigger && healthChecks.length > 0) {
+        const baseUrl = `http://localhost:${httpTrigger.port}`;
+        const outDir = path.join(currentPath, "nodes-gen");
+        void regenStubsWhenReady(baseUrl, outDir);
+    }
     const keepAlive = setInterval(() => { }, 60_000);
     let stopping = false;
     function shutdown() {

package/dist/commands/install/node.d.ts

@@ -1,4 +1,5 @@
 import { Command, type OptionValues } from "../../services/commander.js";
 export declare function install(opts: OptionValues): Promise<void>;
+export declare function nodeInstallHint(importName: string, importPath: string): string;
 declare const _default: Command;
 export default _default;

package/dist/commands/install/node.js

@@ -20,10 +20,6 @@ export async function install(opts) {
             throw new Error("Token is invalid.");
         if (!opts.node)
             throw new Error("Node name is required.");
-        const nodeFilePath = path.resolve(opts.directory, "./src/Nodes.ts");
-        if (!fs.existsSync(nodeFilePath)) {
-            throw new Error("Node.ts file does not exist in the specified directory.");
-        }
         const packageJsonPath = path.resolve(opts.directory, "./package.json");
         if (!fs.existsSync(packageJsonPath)) {
             throw new Error("package.json file does not exist in the specified directory.");
@@ -65,10 +61,7 @@ export async function install(opts) {
             p.log.info(stdout);
         else if (stderr)
             throw new Error(stderr);
-        updateNodeFile(nodeFilePath, {
-            importName: toPascalCase(opts.node),
-            importPath: nodeName,
-        });
+        p.log.warn(nodeInstallHint(toPascalCase(opts.node), nodeName));
         logger.stop("Node installed successfully.");
     }
     catch (error) {
@@ -84,37 +77,8 @@ export async function install(opts) {
 function toPascalCase(input) {
     return input.replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase()).replace(/^./, (s) => s.toLowerCase());
 }
-function updateNodeFile(filePath, newModule) {
-    let fileContent = fs.readFileSync(filePath, "utf-8");
-    const { importName, importPath } = newModule;
-    const importStatement = `import ${importName} from "${importPath}";`;
-    if (!fileContent.includes(importStatement)) {
-        const importLines = fileContent.match(/^import .*;$/gm) || [];
-        const lastImport = importLines[importLines.length - 1];
-        fileContent = fileContent.replace(lastImport, `${lastImport}\n${importStatement}`);
-    }
-    const nodesRegex = /const\s+nodes\s*:\s*\{[^}]+\}\s*=\s*\{([\s\S]*?)\n\};/;
-    const match = fileContent.match(nodesRegex);
-    if (!match)
-        throw new Error("Could not find the `nodes` object.");
-    const objectBody = match[1].trimEnd();
-    const entryKey = importPath.replace(/^@[^/]+\//, "");
-    const newEntry = `\t"${entryKey}": new ${importName}()`;
-    if (objectBody.includes(`"${entryKey}"`)) {
-        p.log.warn(`Node "${entryKey}" is already installed. Skipping...`);
-        return;
-    }
-    const lines = objectBody
-        .split("\n")
-        .filter(Boolean)
-        .map((line) => line.trimEnd());
-    if (lines.length > 0 && !lines[lines.length - 1].endsWith(",")) {
-        lines[lines.length - 1] += ",";
-    }
-    lines.push(newEntry);
-    const newObject = `const nodes: {\n\t[key: string]: NodeBase;\n} = {\n${lines.join("\n")}\n};`;
-    fileContent = fileContent.replace(nodesRegex, newObject);
-    fs.writeFileSync(filePath, `${fileContent.trimEnd()}\n`, "utf-8");
+export function nodeInstallHint(importName, importPath) {
+    return `Nodes.ts registration is deprecated. Import the node directly in a handle workflow: import ${importName} from "${importPath}"; then use step("id", ${importName}, inputs).`;
 }
 export default new Command()
     .command("node")

package/dist/commands/migrate/index.js

@@ -1,7 +1,9 @@
 import { Command } from "commander";
 import { program } from "../../services/commander.js";
 import { migrateNode } from "./node.js";
+import { migrateNodesTs } from "./nodesTs.js";
 import { migratePaths } from "./paths.js";
+import { migrateRefs } from "./refs.js";
 import { migrateWorkflows } from "./workflows.js";
 const migrate = new Command("migrate").description("Migrate nodes and workflows to newer patterns");
 const node = new Command("node")
@@ -30,7 +32,30 @@ const paths = new Command("paths")
     .action(async (options) => {
     await migratePaths(options);
 });
+const refs = new Command("refs")
+    .description("Rewrite pure step input refs to structural handle refs and mark dynamic expressions")
+    .option("-d, --dir <value>", "Path to scan for .ts/.json workflows (defaults to current directory)")
+    .option("--dry-run", "Print what would change without writing files")
+    .option("--backup", "Create .bak files next to each migrated file (default true)")
+    .option("--no-backup", "Skip backup creation")
+    .action(async (options) => {
+    await migrateRefs(options);
+});
+const nodesTs = new Command("nodes-ts")
+    .description("Replace handle-DSL step() string node refs with direct imports or runtime stubs")
+    .option("-d, --dir <value>", "Path to scan for TypeScript workflows (defaults to ./src/workflows)")
+    .option("--nodes <value>", "Path to Nodes.ts (defaults to ./src/Nodes.ts)")
+    .option("--stubs <value>", "Path to generated runtime stubs (defaults to ./nodes-gen)")
+    .option("--delete-nodes", "Delete Nodes.ts only when no string workflow refs remain")
+    .option("--dry-run", "Print what would change without writing files")
+    .option("--backup", "Create .bak files next to each migrated file (default true)")
+    .option("--no-backup", "Skip backup creation")
+    .action(async (options) => {
+    await migrateNodesTs(options);
+});
 migrate.addCommand(node);
 migrate.addCommand(workflows);
 migrate.addCommand(paths);
+migrate.addCommand(refs);
+migrate.addCommand(nodesTs);
 program.addCommand(migrate);

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

@@ -0,0 +1,31 @@
+import type { OptionValues } from "commander";
+type ImportKind = "default" | "named";
+interface ImportRef {
+    kind: ImportKind;
+    importName: string;
+    importPath: string;
+    originFile: string;
+}
+interface RuntimeRef {
+    exportName: string;
+    importPath: string;
+    runtime: string;
+}
+interface Resolver {
+    modules: Map<string, ImportRef>;
+    runtimes: Map<string, RuntimeRef>;
+}
+interface MigrationStats {
+    migrated: number;
+    marked: number;
+}
+export declare function migrateNodesTs(opts: OptionValues): Promise<void>;
+export declare function migrateNodesTsSource(source: string, file: string, resolver: Resolver): {
+    value: string;
+    changed: boolean;
+    stats: MigrationStats;
+};
+export declare function parseNodesMap(source: string, nodesFile: string): Promise<Map<string, ImportRef>>;
+export declare function parseRuntimeStubs(stubsDir: string): Promise<Map<string, RuntimeRef>>;
+export declare function countStringNodeRefs(root: string): Promise<number>;
+export {};