blokctl 1.2.0 → 1.4.0

package/dist/commands/create/project.d.ts

@@ -2,6 +2,9 @@ import type { OptionValues } from "commander";
 export declare function createProject(opts: OptionValues, version: string, currentPath?: boolean, localRepoPath?: string): Promise<void>;
 export declare function generateSharedNodesFile(_triggers: string[], _repoSource: string): string;
 export declare function generateSharedWorkflowsFile(triggers: string[], runtimeKinds?: string[], examples?: boolean): string;
+export declare function generateTriggerEntryFile(triggerKind: string, selectedTriggers?: string[]): string;
+export declare function generateCronExampleWorkflowFile(): string;
+export declare function generateCronServerFile(): string;
 export declare function updateQueueProvider(triggerDestDir: string, provider: string, explicit: boolean): void;
 export declare function getProviderDependencies(triggers: string[], pubsubProvider: string, queueProvider: string, explicitQueueProvider?: boolean): Record<string, string>;
 export declare function getProviderEnvVars(triggers: string[], pubsubProvider: string, queueProvider: string, explicitQueueProvider?: boolean): string;

package/dist/commands/create/project.js

@@ -1,6 +1,7 @@
 import child_process from "node:child_process";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import util from "node:util";
 import * as p from "@clack/prompts";
 import figlet from "figlet";
@@ -14,7 +15,7 @@ import { rewriteObservabilityEnvBlock } from "../../services/observability-mutat
 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 { computeDefaultConstraint, formatVersionMismatch, satisfiesConstraint } from "../../services/semver-utils.js";
 import { resolveObservabilitySelection } from "../observability/apply.js";
 import { OBSERVABILITY_MODULE_IDS, allObservabilityModules, getObservabilityModule, } from "../observability/descriptor.js";
 import { agents_md, claude_md, examples_url, node_file, package_dependencies, package_dev_dependencies, } from "./utils/Examples.js";
@@ -22,7 +23,8 @@ 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 = "v1.2.0";
+const GITHUB_REPO_RELEASE_TAG = "v1.4.0";
+const BUNDLED_SCAFFOLD_REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scaffold-repo");
 const RUNTIME_HELLO_EXAMPLES = {
     go: "runtime-go-hello.ts",
     rust: "runtime-rust-hello.ts",
@@ -55,7 +57,7 @@ export async function createProject(opts, version, currentPath = false, localRep
     let examples = opts.examples ?? false;
     let selectedRuntimeKinds = opts.runtimes ? parseCommaSeparated(opts.runtimes) : ["node"];
     let selectedManager = opts.packageManager || "npm";
-    let pubsubProvider = opts.pubsubProvider || "gcp";
+    let pubsubProvider = opts.pubsubProvider || "nats";
     let queueProvider = opts.queueProvider || "kafka";
     let explicitQueueProvider = Boolean(opts.queueProvider);
     let selectedObsTier = opts.obsStack ? parseObsTier(opts.obsStack) : "none";
@@ -154,6 +156,7 @@ export async function createProject(opts, version, currentPath = false, localRep
                     ? p.select({
                         message: "Select Pub/Sub provider",
                         options: [
+                            { label: "NATS (local, zero cloud setup)", value: "nats" },
                             { label: "Google Cloud Pub/Sub", value: "gcp" },
                             { label: "AWS SNS/SQS", value: "aws" },
                             { label: "Azure Service Bus", value: "azure" },
@@ -212,7 +215,7 @@ export async function createProject(opts, version, currentPath = false, localRep
         });
         projectName = blokctlProject.projectName;
         selectedTriggers = blokctlProject.triggers;
-        pubsubProvider = blokctlProject.pubsubProvider || "gcp";
+        pubsubProvider = blokctlProject.pubsubProvider || "nats";
         explicitQueueProvider = blokctlProject.queueProvider != null;
         queueProvider = blokctlProject.queueProvider || "kafka";
         selectedRuntimeKinds = blokctlProject.runtimes;
@@ -278,14 +281,19 @@ export async function createProject(opts, version, currentPath = false, localRep
         const dirPath = !currentPath ? path.join(process.cwd(), projectName) : process.cwd();
         if (!skipPrompts)
             s.message("Gathering project files");
-        const repoSource = localRepoPath ? path.resolve(localRepoPath) : GITHUB_REPO_LOCAL;
+        let repoSource;
         if (localRepoPath) {
+            repoSource = path.resolve(localRepoPath);
             if (!fsExtra.existsSync(repoSource)) {
                 throw new Error(`Local repo path not found: ${repoSource}`);
             }
             console.log(color.dim(`  Using local repo: ${repoSource}`));
         }
+        else if (fsExtra.existsSync(BUNDLED_SCAFFOLD_REPO)) {
+            repoSource = BUNDLED_SCAFFOLD_REPO;
+        }
         else {
+            repoSource = GITHUB_REPO_LOCAL;
             const githubLocalExists = fsExtra.existsSync(GITHUB_REPO_LOCAL);
             if (githubLocalExists) {
                 fsExtra.removeSync(GITHUB_REPO_LOCAL);
@@ -418,7 +426,10 @@ export async function createProject(opts, version, currentPath = false, localRep
                         fsExtra.copySync(`${triggerSrcDir}/AppRoutes.ts`, `${triggerDestDir}/AppRoutes.ts`);
                     }
                     if (fsExtra.existsSync(`${triggerSrcDir}/workflows`)) {
-                        fsExtra.copySync(`${triggerSrcDir}/workflows`, `${dirPath}/src/workflows/${triggerKind}`);
+                        const devFixtures = /\/(countries-helper|countries-cats-helper|empty)\.ts$|\/workflows\/eval(\/|$)/;
+                        fsExtra.copySync(`${triggerSrcDir}/workflows`, `${dirPath}/src/workflows/${triggerKind}`, {
+                            filter: (src) => !devFixtures.test(src),
+                        });
                     }
                 }
             }
@@ -453,6 +464,14 @@ export async function createProject(opts, version, currentPath = false, localRep
             fsExtra.ensureDirSync(wsServerDir);
             fsExtra.writeFileSync(`${wsServerDir}/WSServer.ts`, generateWSServerFile());
         }
+        if (selectedTriggers.includes("cron")) {
+            const cronServerDir = `${dirPath}/src/triggers/cron/runner`;
+            fsExtra.ensureDirSync(cronServerDir);
+            fsExtra.writeFileSync(`${cronServerDir}/CronServer.ts`, generateCronServerFile());
+            const cronWorkflowDir = `${dirPath}/src/workflows/cron`;
+            fsExtra.ensureDirSync(cronWorkflowDir);
+            fsExtra.writeFileSync(`${cronWorkflowDir}/heartbeat.ts`, generateCronExampleWorkflowFile());
+        }
         for (const triggerKind of selectedTriggers) {
             const triggerNodesDir = `${repoSource}/triggers/${triggerKind}/src/nodes`;
             if (fsExtra.existsSync(triggerNodesDir)) {
@@ -500,13 +519,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             fsExtra.ensureDirSync(`${dirPath}/infra/milvus`);
             fsExtra.copySync(`${repoSource}/infra/development`, `${dirPath}/infra/postgresql`);
             fsExtra.copySync(`${repoSource}/infra/milvus`, `${dirPath}/infra/milvus`);
-            const needsHelpers = selectedTriggers.includes("sse") || selectedTriggers.includes("websocket") || selectedTriggers.includes("mcp");
-            const examplesNodesContent = needsHelpers
-                ? node_file
-                    .replace(`import type { NodeBase } from "@blokjs/shared";`, `import type { NodeBase } from "@blokjs/shared";\nimport { HELPER_NODES } from "@blokjs/helpers";`)
-                    .replace(`} = {\n\t"@blokjs/api-call": ApiCall,`, `} = {\n\t...HELPER_NODES,\n\t"@blokjs/api-call": ApiCall,`)
-                : node_file;
-            fsExtra.writeFileSync(`${dirPath}/src/Nodes.ts`, examplesNodesContent);
+            fsExtra.writeFileSync(`${dirPath}/src/Nodes.ts`, node_file);
             fsExtra.copySync(`${repoSource}/sdk`, `${dirPath}/public/sdk`);
             const tsExamplesSrc = `${repoSource}/examples/ts-workflows`;
             const tsExamplesDest = `${dirPath}/src/workflows/examples`;
@@ -551,7 +564,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             "@blokjs/trigger-worker": "triggers/worker",
             "@blokjs/core": "core/core",
         };
-        const BLOKJS_DEP_RANGE = "^1.2.0";
+        const BLOKJS_DEP_RANGE = "^1.4.0";
         for (const depGroup of ["dependencies", "devDependencies", "peerDependencies"]) {
             const deps = packageJsonContent[depGroup];
             if (!deps)
@@ -636,6 +649,16 @@ export async function createProject(opts, version, currentPath = false, localRep
                 ? `file:${path.resolve(repoSource, "triggers/worker")}`
                 : BLOKJS_DEP_RANGE;
         }
+        if (selectedTriggers.includes("cron")) {
+            triggerPackageDeps["@blokjs/trigger-cron"] = localRepoPath
+                ? `file:${path.resolve(repoSource, "triggers/cron")}`
+                : BLOKJS_DEP_RANGE;
+        }
+        if (selectedTriggers.includes("grpc")) {
+            triggerPackageDeps["@blokjs/trigger-grpc"] = localRepoPath
+                ? `file:${path.resolve(repoSource, "triggers/grpc")}`
+                : BLOKJS_DEP_RANGE;
+        }
         if (selectedTriggers.includes("sse")) {
             const sseDeps = {
                 "@blokjs/api-call": localRepoPath
@@ -705,6 +728,14 @@ export async function createProject(opts, version, currentPath = false, localRep
                 const rt = detectedRuntimes.find((r) => r.kind === kind);
                 if (!rt)
                     continue;
+                if (rt.minVersion) {
+                    const constraint = computeDefaultConstraint(rt.minVersion);
+                    if (!rt.version || !satisfiesConstraint(rt.version, constraint)) {
+                        console.log(`\n${formatVersionMismatch(rt.label, rt.version, constraint, rt.installHint)}`);
+                        console.log(color.yellow(`  Skipping ${rt.label} setup. After upgrading, add it with \`blokctl runtime add ${rt.kind}\`.\n`));
+                        continue;
+                    }
+                }
                 try {
                     const config = await setupRuntime(rt, repoSource, dirPath, s);
                     runtimeConfigs.push(config);
@@ -856,6 +887,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             s.stop(error.message);
         if (skipPrompts)
             console.log(error.message);
+        process.exitCode = 1;
     }
 }
 export function generateSharedNodesFile(_triggers, _repoSource) {
@@ -902,23 +934,31 @@ export function generateSharedWorkflowsFile(triggers, runtimeKinds = [], example
         }
         else if (trigger === "sse") {
             imports.push('import SSEStreamDemo from "./workflows/sse/events/stream-demo";');
-            workflowEntries.push('\t"sse-stream-demo": SSEStreamDemo,');
+            workflowEntries.push('\t"sse-stream-demo": await SSEStreamDemo,');
             if (triggers.includes("http")) {
                 imports.push('import SSEPublishDemo from "./workflows/sse/events/publish-demo";');
-                workflowEntries.push('\t"sse-publish-demo": SSEPublishDemo,');
+                workflowEntries.push('\t"sse-publish-demo": await SSEPublishDemo,');
             }
         }
         else if (trigger === "websocket") {
             imports.push('import WSEchoDemo from "./workflows/websocket/events/echo-demo";');
-            workflowEntries.push('\t"ws-echo-demo": WSEchoDemo,');
+            workflowEntries.push('\t"ws-echo-demo": await WSEchoDemo,');
         }
         else if (trigger === "pubsub") {
             imports.push('import OnPubSubMessage from "./workflows/pubsub/messages/on-message";');
-            workflowEntries.push('\t"on-pubsub-message": OnPubSubMessage,');
+            workflowEntries.push('\t"on-pubsub-message": await OnPubSubMessage,');
+            if (triggers.includes("http")) {
+                imports.push('import PublishOrder from "./workflows/pubsub/publish-order";');
+                workflowEntries.push('\t"publish-order": await PublishOrder,');
+            }
         }
         else if (trigger === "queue" || trigger === "worker") {
             imports.push(`import ProcessJob from "./workflows/${trigger}/jobs/process-job";`);
-            workflowEntries.push('\t"process-job": ProcessJob,');
+            workflowEntries.push('\t"process-job": await ProcessJob,');
+        }
+        else if (trigger === "cron") {
+            imports.push('import CronHeartbeat from "./workflows/cron/heartbeat";');
+            workflowEntries.push('\t"cron-heartbeat": await CronHeartbeat,');
         }
     }
     if (examples) {
@@ -948,7 +988,7 @@ ${entriesSection}
 export default workflows;
 `;
 }
-function generateTriggerEntryFile(triggerKind, selectedTriggers = [triggerKind]) {
+export function generateTriggerEntryFile(triggerKind, selectedTriggers = [triggerKind]) {
     if (triggerKind === "http") {
         const sseAlsoSelected = selectedTriggers.includes("sse");
         const wsAlsoSelected = selectedTriggers.includes("websocket");
@@ -1288,6 +1328,63 @@ export default class App {
 if (process.env.DISABLE_TRIGGER_RUN !== "true") {
 	new App().run();
 }
+`;
+    }
+    if (triggerKind === "cron") {
+        return `import { DefaultLogger } from "@blokjs/runner";
+import { type Span, metrics, trace } from "@opentelemetry/api";
+import CronServer from "./runner/CronServer";
+
+export default class App {
+	private cronServer: CronServer = <CronServer>{};
+	protected trigger_initializer = 0;
+	protected initializer = 0;
+	protected tracer = trace.getTracer(
+		process.env.PROJECT_NAME || "trigger-cron-server",
+		process.env.PROJECT_VERSION || "0.0.1",
+	);
+	private logger = new DefaultLogger();
+	protected app_cold_start = metrics.getMeter("default").createGauge("initialization", {
+		description: "Application cold start",
+	});
+
+	constructor() {
+		this.initializer = performance.now();
+		this.cronServer = new CronServer();
+	}
+
+	async run() {
+		this.tracer.startActiveSpan("initialization", async (span: Span) => {
+			await this.cronServer.listen();
+			this.initializer = performance.now() - this.initializer;
+
+			this.logger.log(\`Cron trigger initialized in \${(this.initializer).toFixed(2)}ms\`);
+			this.app_cold_start.record(this.initializer, {
+				pid: process.pid,
+				env: process.env.NODE_ENV,
+				app: process.env.APP_NAME,
+			});
+			span.end();
+		});
+	}
+}
+
+if (process.env.DISABLE_TRIGGER_RUN !== "true") {
+	new App().run();
+}
+`;
+    }
+    if (triggerKind === "grpc") {
+        return `import { GrpcServer } from "@blokjs/trigger-grpc";
+import nodes from "../../Nodes";
+import workflows from "../../Workflows";
+
+const host = process.env.GRPC_HOST || "0.0.0.0";
+const port = Number(process.env.GRPC_PORT || process.env.PORT || 4003);
+
+if (process.env.DISABLE_TRIGGER_RUN !== "true") {
+	new GrpcServer({ host, port, nodes, workflows }).start();
+}
 `;
     }
     return `// Entry point for ${triggerKind} trigger
@@ -1295,6 +1392,45 @@ if (process.env.DISABLE_TRIGGER_RUN !== "true") {
 console.log("${triggerKind} trigger not yet implemented");
 `;
 }
+export function generateCronExampleWorkflowFile() {
+    return `import { node, step, workflow } from "@blokjs/core";
+
+/**
+ * Cron heartbeat — fires on a schedule, NOT on an HTTP request. \`blokctl dev\`
+ * boots it via src/triggers/cron/index.ts and it fires every minute. The
+ * schedule accepts an optional leading seconds field (e.g. \`* * * * * *\` for
+ * every second). Add more cron workflows by exporting them and registering
+ * them in src/Workflows.ts.
+ */
+export default workflow(
+	"Cron Heartbeat",
+	{ version: "1.0.0", trigger: { cron: { schedule: "* * * * *", timezone: "UTC" } } },
+	() => {
+		step("heartbeat", node("@blokjs/expr"), { expression: "({ ok: true, at: Date.now() })" }, { ephemeral: true });
+	},
+);
+`;
+}
+export function generateCronServerFile() {
+    return `import { CronTrigger } from "@blokjs/trigger-cron";
+import nodes from "../../../Nodes";
+import workflows from "../../../Workflows";
+
+/**
+ * CronServer — the cron trigger for this project.
+ *
+ * CronTrigger.listen() populates the NodeMap, registers workflows with the
+ * WorkflowRegistry, then schedules a CronJob for every workflow whose trigger
+ * is \`{ cron: { schedule, timezone? } }\`. There is no port to bind — the
+ * scheduled job timers keep the process alive. Non-cron workflows sharing this
+ * Workflows.ts are ignored by the scheduler (they run under their own trigger).
+ */
+export default class CronServer extends CronTrigger {
+	protected nodes: Record<string, import("@blokjs/runner").BlokService<unknown>> = nodes;
+	protected workflows: Record<string, import("@blokjs/helper").WorkflowV2Builder> = workflows;
+}
+`;
+}
 function generateSSEServerFile() {
     return `import { serve } from "@hono/node-server";
 import { DefaultLogger, NodeMap, WorkflowRegistry } from "@blokjs/runner";
@@ -1581,8 +1717,12 @@ function updatePubSubProvider(triggerDestDir, provider) {
         },
     };
     const config = adapterConfigs[provider];
-    if (!config)
+    if (!config) {
+        content = content.replace(/import \{ GCPPubSubAdapter, PubSubTrigger \} from ["']@blokjs\/trigger-pubsub["'];/, 'import { PubSubTrigger } from "@blokjs/trigger-pubsub";');
+        content = content.replace(/\n\tprotected adapter = new GCPPubSubAdapter\(\{[\s\S]*?\}\);\n/, "");
+        fsExtra.writeFileSync(serverPath, content);
         return;
+    }
     content = content.replace(/import \{ (\w+), (\w+) \} from ["']@blokjs\/trigger-pubsub["'];/, `import { ${config.importName}, PubSubTrigger } from "@blokjs/trigger-pubsub";`);
     content = content.replace(/(export default class \w+ extends PubSubTrigger \{[\s\S]*?)\n\tprotected adapter = new \w+\(\{[\s\S]*?\}\);/, `$1\n\tprotected adapter = ${config.init};`);
     fsExtra.writeFileSync(serverPath, content);
@@ -1640,6 +1780,7 @@ export function updateQueueProvider(triggerDestDir, provider, explicit) {
 export function getProviderDependencies(triggers, pubsubProvider, queueProvider, explicitQueueProvider = false) {
     const deps = {};
     const pubsubProviderDeps = {
+        nats: { nats: "^2.28.0" },
         gcp: { "@google-cloud/pubsub": "^5.0.0" },
         aws: { "@aws-sdk/client-sns": "^3.980.0", "@aws-sdk/client-sqs": "^3.980.0" },
         azure: { "@azure/service-bus": "^7.9.5" },
@@ -1664,6 +1805,10 @@ export function getProviderDependencies(triggers, pubsubProvider, queueProvider,
 export function getProviderEnvVars(triggers, pubsubProvider, queueProvider, explicitQueueProvider = false) {
     const lines = [];
     const pubsubEnvVars = {
+        nats: `
+# NATS (local pub/sub broker — zero cloud setup)
+NATS_SERVERS=localhost:4222
+BLOK_PUBSUB_ADAPTER=nats`,
         gcp: `
 # Google Cloud Pub/Sub
 GCP_PROJECT_ID=my-project

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

@@ -1,4 +1,4 @@
-declare const node_file = "import { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport ApiCall from \"@blokjs/api-call\";\nimport IfElse from \"@blokjs/if-else\";\nimport { discoverNodes } from \"@blokjs/runner\";\nimport type { NodeBase } from \"@blokjs/shared\";\nimport ExampleNodes from \"./nodes/examples/index\";\n\n// Published nodes (npm) + the example bundle are registered explicitly below.\n// Your OWN nodes under 'nodes/<name>/index.ts' are AUTO-DISCOVERED and registered\n// by their defineNode({ name }) \u2014 you never edit this file to add a node.\nconst here = dirname(fileURLToPath(import.meta.url));\nconst local = await discoverNodes(join(here, \"nodes\"));\n\nconst explicit: NodeBase[] = [ApiCall, IfElse, ...(Object.values(ExampleNodes) as NodeBase[])];\n\n// Map keys are cosmetic \u2014 the runner registers each node under its own node.name\n// (the canonical 'use:' ref). Duplicate refs throw at startup.\nconst nodes: { [key: string]: NodeBase } = {};\nfor (const node of [...explicit, ...local]) {\n\tnodes[(node as { name: string }).name] = node;\n}\n\nexport default nodes;\n";
+declare const node_file = "import { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport ApiCall from \"@blokjs/api-call\";\nimport { HELPER_NODES } from \"@blokjs/helpers\";\nimport IfElse from \"@blokjs/if-else\";\nimport { discoverNodes } from \"@blokjs/runner\";\nimport type { NodeBase } from \"@blokjs/shared\";\nimport ExampleNodes from \"./nodes/examples/index\";\n\n// Published nodes (npm) + the example bundle are registered explicitly below.\n// Your OWN nodes under 'nodes/<name>/index.ts' are AUTO-DISCOVERED and registered\n// by their defineNode({ name }) \u2014 you never edit this file to add a node.\nconst here = dirname(fileURLToPath(import.meta.url));\nconst local = await discoverNodes(join(here, \"nodes\"));\n\nconst explicit: NodeBase[] = [\n\tApiCall,\n\tIfElse,\n\t...(Object.values(HELPER_NODES) as unknown as NodeBase[]),\n\t...(Object.values(ExampleNodes) as NodeBase[]),\n];\n\n// Map keys are cosmetic \u2014 the runner registers each node under its own node.name\n// (the canonical 'use:' ref). Duplicate refs throw at startup.\nconst nodes: { [key: string]: NodeBase } = {};\nfor (const node of [...explicit, ...local]) {\n\tnodes[(node as { name: string }).name] = node;\n}\n\nexport default nodes;\n";
 declare const package_dependencies: {
     ai: string;
     "@ai-sdk/openai": string;
@@ -13,7 +13,7 @@ declare const package_dev_dependencies: {
     "@types/pg": string;
 };
 declare const python3_file = "from pydantic import BaseModel\n\nfrom blok import node\nfrom blok.types.context import Context\n\n\nclass Input(BaseModel):\n    \"\"\"Validated inputs for the {{NODE_NAME}} node.\"\"\"\n\n    name: str = \"world\"\n\n\nclass Output(BaseModel):\n    message: str\n\n\n@node(\"{{NODE_NAME}}\", \"Describe what {{NODE_NAME}} does\")\ndef run(ctx: Context, input: Input) -> Output:\n    # `input` is already validated against Input; the return is validated\n    # against Output and serialized for you.\n    return Output(message=f\"Hello, {input.name}!\")\n";
-declare const examples_url = "\nExamples:\n1- Open \"workflow-docs.json\" in your browser at http://localhost:4000/workflow-docs\n2- Open \"db-manager.json\" in your browser at http://localhost:4000/db-manager\n3- Open \"dashboard-gen.json\" in your browser at http://localhost:4000/dashboard-gen\n4- Open \"countries.json\" in your browser at http://localhost:4000/countries\n5- Open \"chat.json\" in your browser at http://localhost:4000/chat (set OPENROUTER_API_KEY first)\n6- Open \"chat-memory.json\" in your browser at http://localhost:4000/chat-memory (needs OPENROUTER_API_KEY + Redis at REDIS_URL)\n7- Webhook router: POST /webhooks/{stripe,github,linear} with signed bodies \u2014 set the matching *_WEBHOOK_SECRET env vars (needs --triggers webhook)\n8- LLM agent w/ tool calls: open http://localhost:4000/agent \u2014 model picks between get_weather and calculate tools (needs OPENROUTER_API_KEY + Redis)\n9- 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)\n10- Trigger references (NOT http): workflows/json/{cron-heartbeat,pubsub-on-order,websocket-echo}.json demonstrate the cron, pubsub, and websocket triggers \u2014 read AGENTS.md \"Choosing a trigger\" to pick the right one by intent instead of defaulting to HTTP.\n\nFor more documentation, visit src/nodes/examples/README.md. The first three examples require a PostgreSQL database to function.\n";
+declare const examples_url = "\nExamples:\n1- Open \"workflow-docs.json\" in your browser at http://localhost:4000/workflow-docs\n2- Open \"db-manager.json\" in your browser at http://localhost:4000/db-manager\n3- Open \"dashboard-gen.json\" in your browser at http://localhost:4000/dashboard-gen\n4- Open \"countries.json\" in your browser at http://localhost:4000/countries\n5- Open \"chat.json\" in your browser at http://localhost:4000/chat (set OPENROUTER_API_KEY first)\n6- Open \"chat-memory.json\" in your browser at http://localhost:4000/chat-memory (needs OPENROUTER_API_KEY + Redis at REDIS_URL)\n7- Webhook router: POST /webhooks/{stripe,github,linear} with signed bodies \u2014 set the matching *_WEBHOOK_SECRET env vars (needs --triggers webhook)\n8- LLM agent w/ tool calls: open http://localhost:4000/agent \u2014 model picks between get_weather and calculate tools (needs OPENROUTER_API_KEY + Redis)\n9- 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)\n10- 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 \u2014 read AGENTS.md \"Choosing a trigger\" to pick the right one by intent instead of defaulting to HTTP.\n\nFor more documentation, visit src/nodes/examples/README.md.\n";
 declare const workflow_template = "import { http, node, step, workflow } from \"@blokjs/core\";\n\n/**\n * {{WORKFLOW_NAME}}\n *\n * Add steps with step(\"id\", node, inputs). Read a step's output downstream via\n * the handle it returns (const user = step(...); ... user.name). Control flow:\n * branch / forEach / switchOn / tryCatch \u2014 all from @blokjs/core.\n */\nexport default workflow(\n\t\"{{WORKFLOW_NAME}}\",\n\t{ version: \"1.0.0\", trigger: http.get(\"{{WORKFLOW_PATH}}\") },\n\t(req) => {\n\t\t// Echo the request body back. @blokjs/respond writes the HTTP response,\n\t\t// so mark it ephemeral (no state slot needed).\n\t\tstep(\"echo\", node(\"@blokjs/respond\"), { body: req.body }, { ephemeral: true });\n\t},\n);\n";
 declare const supervisord_nodejs = "\n[supervisord]\nnodaemon=true\n\n[program:nodejs_app]\ncommand=npm start\ndirectory=/app\nautostart=true\nautorestart=true\nstderr_logfile=/var/log/nodejs.err.log\nstdout_logfile=/var/log/nodejs.out.log\n";
 declare const supervisord_python = "\n[program:python_app]\ncommand=python3 /app/.blok/runtimes/python3/server.py\ndirectory=/app\nautostart=true\nautorestart=true\nstderr_logfile=/var/log/python.err.log\nstdout_logfile=/var/log/python.out.log\n";

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,9 +75,9 @@ 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.
+For more documentation, visit src/nodes/examples/README.md.
 `;
 const workflow_template = `import { http, node, step, workflow } from "@blokjs/core";
 

package/dist/commands/dev/index.js

@@ -4,7 +4,7 @@ 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);
@@ -106,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);
@@ -198,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`);
             }

package/dist/commands/runtime/add.js

@@ -5,7 +5,7 @@ import color from "picocolors";
 import { isNonInteractive } from "../../services/non-interactive.js";
 import { detectRuntimes, getRuntimeDefinition } from "../../services/runtime-detector.js";
 import { ensureRuntimeGitignore, rewriteRuntimeEnvBlock, rewriteSupervisordRuntimes, runtimeEnvKey, withRuntime, } from "../../services/runtime-mutations.js";
-import { setupRuntime } from "../../services/runtime-setup.js";
+import { buildRuntimeConfig, setupRuntime, } from "../../services/runtime-setup.js";
 import { RuntimeCommandError, assertGrpcPortFree, assertSidecarKind, readConfigSafe, reportRuntimeError, resolveProjectRoot, resolveSdkSource, } from "./shared.js";
 export async function runtimeAdd(kindArg, options) {
     try {
@@ -54,6 +54,31 @@ export async function runtimeAdd(kindArg, options) {
         const sdkDir = path.join(root, ".blok", "runtimes", kind);
         const alreadyInstalled = Boolean(config.runtimes?.[kind]) || fs.existsSync(sdkDir);
         p.intro(color.inverse(` Add ${def.label} runtime `));
+        if (options.enable === true) {
+            if (config.runtimes?.[kind]) {
+                p.outro(color.dim(`${def.label} is already wired into .blok/config.json.`));
+                return;
+            }
+            if (!fs.existsSync(sdkDir)) {
+                throw new RuntimeCommandError(`${def.label} isn't scaffolded at ${path.relative(root, sdkDir)}. Run \`blokctl runtime add ${kind}\` (without --enable) to install it first.`);
+            }
+            const rt = (detected ?? (await detectRuntimes())).find((d) => d.kind === kind);
+            if (!rt)
+                throw new RuntimeCommandError(`Unknown runtime "${kind}".`);
+            const grpcPort = grpcPortOverride ?? rt.defaultGrpcPort;
+            const clash = Object.values(config.runtimes ?? {}).find((rc) => rc.kind !== kind && rc.grpcPort === grpcPort);
+            if (clash) {
+                throw new RuntimeCommandError(`gRPC port ${grpcPort} is already used by the ${clash.label} runtime. Pass --grpc-port <n> to pick another.`);
+            }
+            const rc = buildRuntimeConfig(rt, root);
+            if (grpcPortOverride !== undefined) {
+                rc.grpcPort = grpcPortOverride;
+                if (rc.grpcStartCmd)
+                    rc.grpcStartCmd = rc.grpcStartCmd.split(String(rt.defaultGrpcPort)).join(String(grpcPortOverride));
+            }
+            finalizeRuntime(root, config, rc, kind, def.label);
+            return;
+        }
         if (alreadyInstalled && options.force !== true) {
             if (nonInteractive) {
                 p.outro(color.dim(`${def.label} is already installed. Re-run with --force to reinstall.`));
@@ -107,37 +132,75 @@ export async function runtimeAdd(kindArg, options) {
                 rc.grpcStartCmd = rc.grpcStartCmd.split(String(rt.defaultGrpcPort)).join(String(grpcPortOverride));
         }
         s.stop(`${def.label} runtime ready`);
-        const nextConfig = withRuntime(config, rc);
-        const remaining = Object.values(nextConfig.runtimes ?? {});
-        fs.mkdirSync(path.join(root, ".blok"), { recursive: true });
-        fs.writeFileSync(path.join(root, ".blok", "config.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
-        const envPath = path.join(root, ".env.local");
-        const envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
-        fs.writeFileSync(envPath, rewriteRuntimeEnvBlock(envContent, remaining));
-        const supervisordPath = path.join(root, "supervisord.conf");
-        if (fs.existsSync(supervisordPath)) {
-            fs.writeFileSync(supervisordPath, rewriteSupervisordRuntimes(fs.readFileSync(supervisordPath, "utf8"), remaining));
-        }
-        const gitignorePath = path.join(root, ".gitignore");
-        if (fs.existsSync(gitignorePath)) {
-            const before = fs.readFileSync(gitignorePath, "utf8");
-            const after = ensureRuntimeGitignore(before);
-            if (after !== before)
-                fs.writeFileSync(gitignorePath, after);
+        if (stampHelloExample(root, source, kind)) {
+            p.log.success(`Shipped the ${def.label} hello example — ${color.cyan(`POST /runtimes/${kind}/hello`)} (registered in src/Workflows.ts)`);
         }
-        p.note([
-            `${color.green("✓")} .blok/config.json   ${color.dim(`runtimes.${kind}`)}`,
-            `${color.green("✓")} .env.local          ${color.dim(`RUNTIME_${runtimeEnvKey(kind)}_GRPC_PORT=${rc.grpcPort}`)}`,
-            fs.existsSync(supervisordPath)
-                ? `${color.green("✓")} supervisord.conf    ${color.dim(`[program:${kind}_runtime]`)}`
-                : "",
-            `${color.green("✓")} runtimes/${kind}/nodes/  ${color.dim("(your runtime nodes go here)")}`,
-        ]
-            .filter(Boolean)
-            .join("\n"), `${def.label} added`);
-        p.outro(`Run ${color.cyan("blokctl dev")} to start it, then add ${color.cyan(`type: "runtime.${kind}"`)} steps to your workflows.`);
+        finalizeRuntime(root, config, rc, kind, def.label);
     }
     catch (err) {
         reportRuntimeError(err);
     }
 }
+function stampHelloExample(root, source, kind) {
+    const file = `runtime-${kind}-hello.ts`;
+    const srcFile = path.join(source, "examples", "ts-workflows", file);
+    const examplesDir = path.join(root, "src", "workflows", "examples");
+    const workflowsTs = path.join(root, "src", "Workflows.ts");
+    if (!fs.existsSync(srcFile) || !fs.existsSync(examplesDir) || !fs.existsSync(workflowsTs))
+        return false;
+    const importName = `Runtime${kind.charAt(0).toUpperCase()}${kind.slice(1)}Hello`;
+    const importLine = `import ${importName} from "./workflows/examples/runtime-${kind}-hello";`;
+    const entryLine = `\t"runtime-${kind}-hello": ${importName},`;
+    const content = fs.readFileSync(workflowsTs, "utf8");
+    if (content.includes(`./workflows/examples/runtime-${kind}-hello`)) {
+        fs.copyFileSync(srcFile, path.join(examplesDir, file));
+        return true;
+    }
+    const lines = content.split("\n");
+    const openIdx = lines.findIndex((l) => /^const workflows\b.*=\s*\{\s*$/.test(l));
+    let lastImport = -1;
+    for (let i = 0; i < (openIdx === -1 ? lines.length : openIdx); i++) {
+        if (/^import /.test(lines[i]))
+            lastImport = i;
+    }
+    if (openIdx === -1 || lastImport === -1) {
+        p.log.warn(`src/Workflows.ts doesn't look generated — register the ${kind} hello example yourself:\n  ${importLine}\n  ${entryLine.trim()}`);
+        return false;
+    }
+    lines.splice(openIdx + 1, 0, entryLine);
+    lines.splice(lastImport + 1, 0, importLine);
+    fs.copyFileSync(srcFile, path.join(examplesDir, file));
+    fs.writeFileSync(workflowsTs, lines.join("\n"));
+    return true;
+}
+function finalizeRuntime(root, config, rc, kind, label) {
+    const nextConfig = withRuntime(config, rc);
+    const remaining = Object.values(nextConfig.runtimes ?? {});
+    fs.mkdirSync(path.join(root, ".blok"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".blok", "config.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
+    const envPath = path.join(root, ".env.local");
+    const envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+    fs.writeFileSync(envPath, rewriteRuntimeEnvBlock(envContent, remaining));
+    const supervisordPath = path.join(root, "supervisord.conf");
+    if (fs.existsSync(supervisordPath)) {
+        fs.writeFileSync(supervisordPath, rewriteSupervisordRuntimes(fs.readFileSync(supervisordPath, "utf8"), remaining));
+    }
+    const gitignorePath = path.join(root, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+        const before = fs.readFileSync(gitignorePath, "utf8");
+        const after = ensureRuntimeGitignore(before);
+        if (after !== before)
+            fs.writeFileSync(gitignorePath, after);
+    }
+    p.note([
+        `${color.green("✓")} .blok/config.json   ${color.dim(`runtimes.${kind}`)}`,
+        `${color.green("✓")} .env.local          ${color.dim(`RUNTIME_${runtimeEnvKey(kind)}_GRPC_PORT=${rc.grpcPort}`)}`,
+        fs.existsSync(supervisordPath)
+            ? `${color.green("✓")} supervisord.conf    ${color.dim(`[program:${kind}_runtime]`)}`
+            : "",
+        `${color.green("✓")} runtimes/${kind}/nodes/  ${color.dim("(your runtime nodes go here)")}`,
+    ]
+        .filter(Boolean)
+        .join("\n"), `${label} added`);
+    p.outro(`Run ${color.cyan("blokctl dev")} to start it, then add ${color.cyan(`type: "runtime.${kind}"`)} steps to your workflows.`);
+}

package/dist/commands/runtime/index.js

@@ -15,6 +15,7 @@ runtime
     .option("--local <path>", "Use a local blok repo for SDK source instead of fetching by version")
     .option("--grpc-port <port>", "Override the gRPC port for this runtime")
     .option("--force", "Reinstall if the runtime is already present")
+    .option("--enable", "Wire an already-scaffolded runtime (SDK dir on disk) into config.json without reinstalling")
     .option("--skip-toolchain-check", "Add even if the language toolchain isn't detected")
     .option("-y, --yes", "Skip prompts (non-interactive)")
     .action(async (runtimeArg, options) => {

package/dist/commands/runtime/shared.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import * as p from "@clack/prompts";
 import color from "picocolors";
 import simpleGit from "simple-git";
@@ -62,6 +63,9 @@ export async function resolveSdkSource(projectRoot, localOverride, onProgress) {
         }
         return resolved;
     }
+    const bundled = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scaffold-repo");
+    if (fs.existsSync(path.join(bundled, "sdks")))
+        return bundled;
     const tag = readFrameworkTag(projectRoot);
     if (!tag) {
         throw new RuntimeCommandError("Couldn't determine the project's Blok version from package.json. Pass --local <path-to-blok-repo> to point at a matching SDK source.");