blokctl 0.6.4 → 0.6.5

package/dist/commands/create/project.js

@@ -17,7 +17,7 @@ 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.6.4";
+const GITHUB_REPO_RELEASE_TAG = "v0.6.5";
 fsExtra.ensureDirSync(HOME_DIR);
 const options = {
     baseDir: HOME_DIR,
@@ -111,7 +111,12 @@ export async function createProject(opts, version, currentPath = false, localRep
                     message: "Select triggers to install",
                     options: [
                         { label: "HTTP", value: "http", hint: "REST APIs (port 4000)" },
-                        { label: "SSE", value: "sse", hint: "Real-time push (port 4001)" },
+                        { label: "SSE", value: "sse", hint: "Real-time server push (mounts on HTTP port)" },
+                        {
+                            label: "WebSocket",
+                            value: "websocket",
+                            hint: "Bi-directional real-time (mounts on HTTP port)",
+                        },
                         { label: "Queue", value: "queue", hint: "Kafka/RabbitMQ/SQS/Redis (port 4005)" },
                         { label: "Pub/Sub", value: "pubsub", hint: "GCP/AWS/Azure messaging (port 4006)" },
                     ],
@@ -257,6 +262,14 @@ export async function createProject(opts, version, currentPath = false, localRep
         fsExtra.ensureDirSync(`${dirPath}/src/nodes`);
         fsExtra.ensureDirSync(`${dirPath}/src/workflows`);
         const triggerConfigs = selectedTriggers.map((kind) => createTriggerConfig(kind));
+        const mountedOnHttp = new Set();
+        if (selectedTriggers.includes("http")) {
+            for (const kind of ["sse", "websocket"]) {
+                if (selectedTriggers.includes(kind))
+                    mountedOnHttp.add(kind);
+            }
+        }
+        const spawnedTriggerConfigs = triggerConfigs.filter((tc) => !mountedOnHttp.has(tc.kind));
         const primaryTrigger = selectedTriggers[0];
         const primaryTriggerDir = primaryTrigger === "pubsub" || primaryTrigger === "queue"
             ? `${repoSource}/triggers/${primaryTrigger === "queue" ? "worker" : primaryTrigger}/template`
@@ -326,7 +339,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             }
             else {
                 const triggerSrcDir = `${repoSource}/triggers/${triggerKind}/src`;
-                if (triggerKind === "sse") {
+                if (triggerKind === "sse" || triggerKind === "websocket") {
                     const entries = fsExtra.readdirSync(triggerSrcDir, { withFileTypes: true });
                     for (const entry of entries) {
                         const src = `${triggerSrcDir}/${entry.name}`;
@@ -371,9 +384,19 @@ export async function createProject(opts, version, currentPath = false, localRep
         const sharedWorkflowsContent = generateSharedWorkflowsFile(selectedTriggers);
         fsExtra.writeFileSync(`${dirPath}/src/Workflows.ts`, sharedWorkflowsContent);
         for (const triggerKind of selectedTriggers) {
-            const entryContent = generateTriggerEntryFile(triggerKind);
+            const entryContent = generateTriggerEntryFile(triggerKind, selectedTriggers);
             fsExtra.writeFileSync(`${dirPath}/src/triggers/${triggerKind}/index.ts`, entryContent);
         }
+        if (selectedTriggers.includes("sse")) {
+            const sseServerDir = `${dirPath}/src/triggers/sse/runner`;
+            fsExtra.ensureDirSync(sseServerDir);
+            fsExtra.writeFileSync(`${sseServerDir}/SSEServer.ts`, generateSSEServerFile());
+        }
+        if (selectedTriggers.includes("websocket")) {
+            const wsServerDir = `${dirPath}/src/triggers/websocket/runner`;
+            fsExtra.ensureDirSync(wsServerDir);
+            fsExtra.writeFileSync(`${wsServerDir}/WSServer.ts`, generateWSServerFile());
+        }
         for (const triggerKind of selectedTriggers) {
             const triggerNodesDir = `${repoSource}/triggers/${triggerKind}/src/nodes`;
             if (fsExtra.existsSync(triggerNodesDir)) {
@@ -430,13 +453,20 @@ export async function createProject(opts, version, currentPath = false, localRep
         const workspacePackageMap = {
             "@blokjs/api-call": "nodes/web/api-call@1.0.0",
             "@blokjs/helper": "core/workflow-helper",
+            "@blokjs/helpers": "nodes/utility/helpers@1.0.0",
             "@blokjs/if-else": "nodes/control-flow/if-else@1.0.0",
+            "@blokjs/react": "nodes/web/react@1.0.0",
             "@blokjs/runner": "core/runner",
             "@blokjs/shared": "core/shared",
+            "@blokjs/trigger-cron": "triggers/cron",
+            "@blokjs/trigger-grpc": "triggers/grpc",
             "@blokjs/trigger-pubsub": "triggers/pubsub",
+            "@blokjs/trigger-sse": "triggers/sse",
+            "@blokjs/trigger-webhook": "triggers/webhook",
+            "@blokjs/trigger-websocket": "triggers/websocket",
             "@blokjs/trigger-worker": "triggers/worker",
         };
-        const BLOKJS_DEP_RANGE = "^0.6.4";
+        const BLOKJS_DEP_RANGE = "^0.6.5";
         for (const depGroup of ["dependencies", "devDependencies", "peerDependencies"]) {
             const deps = packageJsonContent[depGroup];
             if (!deps)
@@ -510,6 +540,52 @@ export async function createProject(opts, version, currentPath = false, localRep
                 ? `file:${path.resolve(repoSource, "triggers/worker")}`
                 : BLOKJS_DEP_RANGE;
         }
+        if (selectedTriggers.includes("sse")) {
+            const sseDeps = {
+                "@blokjs/api-call": localRepoPath
+                    ? `file:${path.resolve(repoSource, "nodes/web/api-call@1.0.0")}`
+                    : BLOKJS_DEP_RANGE,
+                "@blokjs/if-else": localRepoPath
+                    ? `file:${path.resolve(repoSource, "nodes/control-flow/if-else@1.0.0")}`
+                    : BLOKJS_DEP_RANGE,
+                "@blokjs/helpers": localRepoPath
+                    ? `file:${path.resolve(repoSource, "nodes/utility/helpers@1.0.0")}`
+                    : BLOKJS_DEP_RANGE,
+                "@blokjs/trigger-sse": localRepoPath ? `file:${path.resolve(repoSource, "triggers/sse")}` : BLOKJS_DEP_RANGE,
+                "@hono/node-server": "^1.19.9",
+                hono: "^4.11.7",
+                uuid: "^11.1.0",
+            };
+            packageJsonContent.dependencies = {
+                ...packageJsonContent.dependencies,
+                ...sseDeps,
+            };
+        }
+        if (selectedTriggers.includes("websocket")) {
+            const wsDeps = {
+                "@blokjs/api-call": localRepoPath
+                    ? `file:${path.resolve(repoSource, "nodes/web/api-call@1.0.0")}`
+                    : BLOKJS_DEP_RANGE,
+                "@blokjs/if-else": localRepoPath
+                    ? `file:${path.resolve(repoSource, "nodes/control-flow/if-else@1.0.0")}`
+                    : BLOKJS_DEP_RANGE,
+                "@blokjs/helpers": localRepoPath
+                    ? `file:${path.resolve(repoSource, "nodes/utility/helpers@1.0.0")}`
+                    : BLOKJS_DEP_RANGE,
+                "@blokjs/trigger-websocket": localRepoPath
+                    ? `file:${path.resolve(repoSource, "triggers/websocket")}`
+                    : BLOKJS_DEP_RANGE,
+                "@hono/node-server": "^1.19.9",
+                "@hono/node-ws": "^1.3.1",
+                hono: "^4.11.7",
+                uuid: "^11.1.0",
+                ws: "^8.19.0",
+            };
+            packageJsonContent.dependencies = {
+                ...packageJsonContent.dependencies,
+                ...wsDeps,
+            };
+        }
         if (Object.keys(triggerPackageDeps).length > 0) {
             packageJsonContent.dependencies = {
                 ...packageJsonContent.dependencies,
@@ -537,7 +613,7 @@ export async function createProject(opts, version, currentPath = false, localRep
                 fsExtra.appendFileSync(envLocal, envVars);
             }
         }
-        writeProjectConfig(dirPath, runtimeConfigs, triggerConfigs);
+        writeProjectConfig(dirPath, runtimeConfigs, spawnedTriggerConfigs);
         if (triggerConfigs.length > 0) {
             const triggerEnvVars = generateTriggerEnvVars(triggerConfigs);
             fsExtra.appendFileSync(envLocal, triggerEnvVars);
@@ -559,8 +635,8 @@ export async function createProject(opts, version, currentPath = false, localRep
         fsExtra.writeFileSync(packageJson, JSON.stringify(packageJsonContent, null, 2));
         const supervisordConfPath = `${dirPath}/supervisord.conf`;
         let supervisordConfContent = "[supervisord]\nnodaemon=true\n";
-        if (triggerConfigs.length > 0) {
-            supervisordConfContent += generateTriggerSupervisordConfig(triggerConfigs);
+        if (spawnedTriggerConfigs.length > 0) {
+            supervisordConfContent += generateTriggerSupervisordConfig(spawnedTriggerConfigs);
         }
         if (runtimeConfigs.length > 0) {
             supervisordConfContent += generateSupervisordConfig(runtimeConfigs);
@@ -585,8 +661,15 @@ export async function createProject(opts, version, currentPath = false, localRep
             console.log(`Change to the project directory: cd ${projectName}`);
         console.log(`Run the command "npm run dev" to start the development server.`);
         console.log("\nTrigger endpoints:");
+        const httpPort = triggerConfigs.find((tc) => tc.kind === "http")?.port;
         for (const tc of triggerConfigs) {
-            console.log(`  ${tc.label}: http://localhost:${tc.port}/health-check`);
+            if (mountedOnHttp.has(tc.kind) && httpPort !== undefined) {
+                const samplePath = tc.kind === "sse" ? "/sse/demo" : "/ws/echo";
+                console.log(`  ${tc.label}: http://localhost:${httpPort}${samplePath}  (mounted on HTTP)`);
+            }
+            else {
+                console.log(`  ${tc.label}: http://localhost:${tc.port}/health-check`);
+            }
         }
         if (runtimeConfigs.length > 0) {
             console.log("\nRuntime health checks:");
@@ -625,19 +708,25 @@ export async function createProject(opts, version, currentPath = false, localRep
 function generateSharedNodesFile(triggers, _repoSource) {
     const nodeImports = new Set();
     const nodeExports = new Map();
+    let spreadHelperNodes = false;
     nodeImports.add('import ApiCall from "@blokjs/api-call";');
     nodeImports.add('import IfElse from "@blokjs/if-else";');
     nodeImports.add('import type { BlokService } from "@blokjs/runner";');
     nodeExports.set("@blokjs/api-call", "ApiCall");
     nodeExports.set("@blokjs/if-else", "IfElse");
+    if (triggers.includes("sse") || triggers.includes("websocket")) {
+        nodeImports.add('import { HELPER_NODES } from "@blokjs/helpers";');
+        spreadHelperNodes = true;
+    }
     const importLines = Array.from(nodeImports).join("\n");
     const exportEntries = Array.from(nodeExports.entries())
         .map(([key, value]) => `\t"${key}": ${value},`)
         .join("\n");
+    const recordBody = spreadHelperNodes ? `\t...HELPER_NODES,\n${exportEntries}` : exportEntries;
     return `${importLines}
 
 const nodes: Record<string, BlokService<unknown>> = {
-${exportEntries}
+${recordBody}
 };
 
 export default nodes;
@@ -651,7 +740,16 @@ function generateSharedWorkflowsFile(triggers) {
             imports.push("// HTTP workflows are auto-discovered from workflows/json/");
         }
         else if (trigger === "sse") {
-            imports.push("// SSE workflows: register in this Workflows record manually");
+            imports.push('import SSEStreamDemo from "./workflows/sse/events/stream-demo";');
+            workflowEntries.push('\t"sse-stream-demo": SSEStreamDemo,');
+            if (triggers.includes("http")) {
+                imports.push('import SSEPublishDemo from "./workflows/sse/events/publish-demo";');
+                workflowEntries.push('\t"sse-publish-demo": SSEPublishDemo,');
+            }
+        }
+        else if (trigger === "websocket") {
+            imports.push('import WSEchoDemo from "./workflows/websocket/events/echo-demo";');
+            workflowEntries.push('\t"ws-echo-demo": WSEchoDemo,');
         }
         else if (trigger === "pubsub") {
             imports.push('import OnPubSubMessage from "./workflows/pubsub/messages/on-message";');
@@ -674,11 +772,87 @@ ${entriesSection}
 export default workflows;
 `;
 }
-function generateTriggerEntryFile(triggerKind) {
+function generateTriggerEntryFile(triggerKind, selectedTriggers = [triggerKind]) {
     if (triggerKind === "http") {
+        const sseAlsoSelected = selectedTriggers.includes("sse");
+        const wsAlsoSelected = selectedTriggers.includes("websocket");
+        const needsShared = sseAlsoSelected || wsAlsoSelected;
+        const sharedHelperImports = needsShared
+            ? `\nimport { NodeMap, WorkflowRegistry } from "@blokjs/runner";\nimport sharedNodes from "../../Nodes";\nimport sharedWorkflows from "../../Workflows";`
+            : "";
+        const sseImports = sseAlsoSelected ? `\nimport SSETrigger from "@blokjs/trigger-sse";` : "";
+        const wsImports = wsAlsoSelected ? `\nimport WebSocketTrigger from "@blokjs/trigger-websocket";` : "";
+        const sharedBootstrapPrelude = needsShared
+            ? `\n\n			// Build a NodeMap from the shared Nodes record; both SSE and
+			// WebSocket triggers consume this via setNodeMap so they can
+			// resolve helper nodes (sse-subscribe, sse-stream, ws-reply,
+			// etc.) at workflow run time.
+			const subTriggerNodeMap = new NodeMap();
+			for (const [key, node] of Object.entries(sharedNodes)) {
+				subTriggerNodeMap.addNode(key, node);
+			}
+			// HttpTrigger.buildFileBasedRoutes() calls WorkflowRegistry.clear()
+			// during listen() and re-registers only HTTP-triggered workflows.
+			// SSE / WebSocket workflows aren't HTTP routes, so they're missing
+			// from the registry by the time the sibling trigger walks it.
+			// Add a preCatchAllHook BEFORE the sibling triggers register their
+			// hooks — preCatchAllHooks fire in insertion order, so this hook
+			// injects SSE + WS workflows into the cleared registry first, and
+			// each sibling trigger's hook then sees them and mounts routes.
+			this.httpTrigger.addPreCatchAllHook(() => {
+				const registry = WorkflowRegistry.getInstance();
+				for (const [name, wf] of Object.entries(sharedWorkflows)) {
+					const w = wf as {
+						name?: string;
+						trigger?: { sse?: unknown; websocket?: unknown };
+						_config?: { name?: string; trigger?: { sse?: unknown; websocket?: unknown } };
+					};
+					const triggerCfg = w._config?.trigger ?? w.trigger;
+					if (!triggerCfg) continue;
+					if (!triggerCfg.sse && !triggerCfg.websocket) continue;
+					const resolvedName = w._config?.name ?? w.name ?? name;
+					if (registry.get(resolvedName)) continue;
+					const kind = triggerCfg.sse ? "sse" : "websocket";
+					registry.register({
+						name: resolvedName,
+						source: \`\${kind}:\${name}\`,
+						workflow: (w._config ?? w) as unknown as Parameters<typeof registry.register>[0]["workflow"],
+					});
+				}
+			});`
+            : "";
+        const sseBootstrap = sseAlsoSelected
+            ? `\n			// Mount SSE on the HTTP process's shared Hono app. SSETrigger's
+			// constructor takes the app + the HttpTrigger for pre-catch-all
+			// hook integration; SSE routes register inside that hook so
+			// they win Hono's first-match dispatch over HTTP's legacy
+			// workflow-name catch-all (\`/:workflow{.+}\`).
+			const sseTrigger = new SSETrigger(this.httpTrigger.getApp(), this.httpTrigger);
+			sseTrigger.setNodeMap({
+				nodes: subTriggerNodeMap,
+				workflows: sharedWorkflows as unknown as Parameters<typeof sseTrigger.setNodeMap>[0]["workflows"],
+			});
+			await sseTrigger.listen();`
+            : "";
+        const wsBootstrap = wsAlsoSelected
+            ? `\n			// Mount WebSocket on the HTTP process's shared Hono app.
+			// WebSocketTrigger uses TWO HttpTrigger integration points:
+			// 1. addPreCatchAllHook — registers WS routes (Hono's upgradeWebSocket
+			//    handler) BEFORE the legacy workflow catch-all so /ws/<path>
+			//    upgrades cleanly.
+			// 2. addServerHook — attaches the WS upgrade listener to the
+			//    http.Server returned by HttpTrigger's serve() call.
+			const wsTrigger = new WebSocketTrigger(this.httpTrigger.getApp(), this.httpTrigger);
+			wsTrigger.setNodeMap({
+				nodes: subTriggerNodeMap,
+				workflows: sharedWorkflows as unknown as Parameters<typeof wsTrigger.setNodeMap>[0]["workflows"],
+			});
+			await wsTrigger.listen();`
+            : "";
+        const fullBootstrap = `${sharedBootstrapPrelude}${sseBootstrap}${wsBootstrap}`;
         return `import { DefaultLogger } from "@blokjs/runner";
 import { type Span, metrics, trace } from "@opentelemetry/api";
-import HttpTrigger from "./runner/HttpTrigger";
+import HttpTrigger from "./runner/HttpTrigger";${sharedHelperImports}${sseImports}${wsImports}
 
 export default class App {
 	private httpTrigger: HttpTrigger = <HttpTrigger>{};
@@ -699,7 +873,7 @@ export default class App {
 	}
 
 	async run() {
-		this.tracer.startActiveSpan("initialization", async (span: Span) => {
+		this.tracer.startActiveSpan("initialization", async (span: Span) => {${fullBootstrap}
 			await this.httpTrigger.listen();
 			this.initializer = performance.now() - this.initializer;
 
@@ -726,10 +900,10 @@ if (process.env.DISABLE_TRIGGER_RUN !== "true") {
     if (triggerKind === "sse") {
         return `import { DefaultLogger } from "@blokjs/runner";
 import { type Span, metrics, trace } from "@opentelemetry/api";
-import SSETrigger from "./SSETrigger";
+import SSEServer from "./runner/SSEServer";
 
 export default class App {
-	private sseTrigger: SSETrigger = <SSETrigger>{};
+	private sseServer: SSEServer = <SSEServer>{};
 	protected trigger_initializer = 0;
 	protected initializer = 0;
 	protected tracer = trace.getTracer(
@@ -743,15 +917,59 @@ export default class App {
 
 	constructor() {
 		this.initializer = performance.now();
-		this.sseTrigger = new SSETrigger();
+		this.sseServer = new SSEServer();
 	}
 
 	async run() {
 		this.tracer.startActiveSpan("initialization", async (span: Span) => {
-			await this.sseTrigger.listen();
+			await this.sseServer.listen();
 			this.initializer = performance.now() - this.initializer;
 
-			this.logger.log(\`Server initialized in \${(this.initializer).toFixed(2)}ms\`);
+			this.logger.log(\`SSE 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 === "websocket") {
+        return `import { DefaultLogger } from "@blokjs/runner";
+import { type Span, metrics, trace } from "@opentelemetry/api";
+import WSServer from "./runner/WSServer";
+
+export default class App {
+	private wsServer: WSServer = <WSServer>{};
+	protected trigger_initializer = 0;
+	protected initializer = 0;
+	protected tracer = trace.getTracer(
+		process.env.PROJECT_NAME || "trigger-websocket-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.wsServer = new WSServer();
+	}
+
+	async run() {
+		this.tracer.startActiveSpan("initialization", async (span: Span) => {
+			await this.wsServer.listen();
+			this.initializer = performance.now() - this.initializer;
+
+			this.logger.log(\`WebSocket trigger initialized in \${(this.initializer).toFixed(2)}ms\`);
 			this.app_cold_start.record(this.initializer, {
 				pid: process.pid,
 				env: process.env.NODE_ENV,
@@ -860,6 +1078,222 @@ if (process.env.DISABLE_TRIGGER_RUN !== "true") {
 console.log("${triggerKind} trigger not yet implemented");
 `;
 }
+function generateSSEServerFile() {
+    return `import { serve } from "@hono/node-server";
+import { DefaultLogger, NodeMap, WorkflowRegistry } from "@blokjs/runner";
+import { Hono } from "hono";
+// Import SSETrigger from the @blokjs/trigger-sse npm package — NOT the
+// locally-copied SSETrigger.ts. The @blokjs/sse-publish helper that
+// publisher workflows use imports the in-process bus from this exact
+// module (\`@blokjs/trigger-sse\`'s \`_getSSEBus\`). If SSEServer uses a
+// different module instance (e.g. the local copy), Node treats them
+// as separate modules with separate bus singletons — events from the
+// helper would never reach subscribers on this trigger.
+import SSETrigger from "@blokjs/trigger-sse";
+import nodes from "../../../Nodes";
+import workflows from "../../../Workflows";
+
+type HonoServer = ReturnType<typeof serve>;
+
+/**
+ * SSEServer — concrete SSE trigger implementation.
+ *
+ * Bootstraps an isolated Hono app for the SSE trigger process, hands
+ * it to SSETrigger, populates the shared NodeMap, registers
+ * SSE-triggered workflows with WorkflowRegistry, then binds an HTTP
+ * listener so /<sse-path> requests reach the streamer.
+ *
+ * Two SSE-triggered workflows ship by default (see
+ * src/workflows/sse/events/):
+ *   - stream-demo.ts    GET  /sse/demo        — subscribes to the
+ *                                                in-process bus channel
+ *                                                "sse-demo" and pumps
+ *                                                events as SSE frames.
+ *   - publish-demo.ts   POST /v07-sse-publish — publishes one event to
+ *                                                the "sse-demo" channel
+ *                                                (HTTP trigger; only
+ *                                                routable when the
+ *                                                project also includes
+ *                                                an HTTP trigger).
+ *
+ * Test end-to-end:
+ *   1. curl -N http://localhost:4001/sse/demo
+ *   2. curl -X POST http://localhost:4000/v07-sse-publish \\
+ *           -H 'Content-Type: application/json' \\
+ *           -d '{"event":"hello","data":{"msg":"world"}}'
+ *   3. Watch (1) — the event arrives instantly.
+ */
+export default class SSEServer {
+	private readonly app: Hono = new Hono();
+	private readonly trigger: SSETrigger;
+	private readonly logger = new DefaultLogger();
+	private httpServer: HonoServer | null = null;
+
+	constructor() {
+		this.trigger = new SSETrigger(this.app);
+
+		// Populate the NodeMap with all registered nodes. SSE workflows
+		// run their steps through the same runner machinery as HTTP,
+		// so they need every node referenced in their step list
+		// (sse-subscribe, sse-stream, plus any user-defined nodes).
+		const nodeMap = new NodeMap();
+		for (const [key, node] of Object.entries(nodes)) {
+			nodeMap.addNode(key, node);
+		}
+		this.trigger.setNodeMap({
+			nodes: nodeMap,
+			workflows: workflows as unknown as Parameters<SSETrigger["setNodeMap"]>[0]["workflows"],
+		});
+
+		// Push SSE-triggered workflows into the WorkflowRegistry.
+		// HTTP-companion workflows (e.g., publish-demo) share the same
+		// Workflows.ts but get registered by the HTTP trigger process
+		// in a multi-trigger scaffold. Filtering here prevents the SSE
+		// trigger from trying to mount HTTP routes.
+		//
+		// Note: \`workflow({...})\` from @blokjs/helper returns a frozen
+		// builder { _blokV2, _config, toJson() }. The trigger config we
+		// filter on lives at \`_config.trigger.sse\`, not at the top-level
+		// (\`.trigger.sse\` is the v1 helper-response shape). Supporting
+		// both keeps the registration tolerant of either authoring style.
+		const registry = WorkflowRegistry.getInstance();
+		for (const [name, wf] of Object.entries(workflows)) {
+			const w = wf as {
+				name?: string;
+				trigger?: { sse?: unknown };
+				_config?: { name?: string; trigger?: { sse?: unknown } };
+			};
+			const triggerCfg = w._config?.trigger ?? w.trigger;
+			if (!triggerCfg?.sse) continue;
+			const resolvedName = w._config?.name ?? w.name ?? name;
+			registry.register({
+				name: resolvedName,
+				source: \`sse:\${name}\`,
+				workflow: (w._config ?? w) as unknown as Parameters<typeof registry.register>[0]["workflow"],
+			});
+		}
+	}
+
+	async listen(): Promise<void> {
+		await this.trigger.listen();
+		const port = Number(process.env.TRIGGER_SSE_PORT || process.env.PORT || 4001);
+		this.httpServer = serve({ fetch: this.app.fetch, port }, () => {
+			this.logger.log(\`SSE server listening on http://localhost:\${port}\`);
+		});
+	}
+
+	async stop(): Promise<void> {
+		await this.trigger.stop();
+		this.httpServer?.close();
+	}
+}
+`;
+}
+function generateWSServerFile() {
+    return `import { serve } from "@hono/node-server";
+import { DefaultLogger, NodeMap, WorkflowRegistry } from "@blokjs/runner";
+import { Hono } from "hono";
+// Import from the @blokjs/trigger-websocket npm package — NOT the
+// locally-copied WebSocketTrigger.ts. The WebSocket helper nodes
+// (@blokjs/ws-broadcast, @blokjs/ws-reply, @blokjs/ws-close) look up
+// the active trigger via the singleton accessor exported from the npm
+// package. Using the local copy would create a separate module instance
+// with a separate singleton — helpers would broadcast into a void.
+import WebSocketTrigger from "@blokjs/trigger-websocket";
+import nodes from "../../../Nodes";
+import workflows from "../../../Workflows";
+
+type HonoServer = ReturnType<typeof serve>;
+
+/**
+ * WSServer — concrete WebSocket trigger implementation.
+ *
+ * Bootstraps an isolated Hono app for the WebSocket trigger process,
+ * hands it to WebSocketTrigger, populates the shared NodeMap, registers
+ * WS-triggered workflows with WorkflowRegistry, binds an HTTP listener,
+ * and attaches the WebSocket upgrade handler to the http.Server.
+ *
+ * One WebSocket workflow ships by default (see src/workflows/websocket/
+ * events/):
+ *   - echo-demo.ts    GET /ws/echo  — on \`connect\` greets the client
+ *                                       with \`{event:"connected"}\`; on
+ *                                       each message replies with
+ *                                       \`{event:"echo", original:<msg>}\`.
+ *
+ * Test end-to-end with any WS client:
+ *   1. Connect:          \`wscat -c ws://localhost:4002/ws/echo\`
+ *   2. On connect:       receive \`{"event":"connected","payload":{"ok":true}}\`
+ *   3. Send anything:    \`{"event":"hello","data":{"hi":"there"}}\`
+ *   4. Receive:          \`{"event":"echo","payload":{"original":...}}\`
+ */
+export default class WSServer {
+	private readonly app: Hono = new Hono();
+	private readonly trigger: WebSocketTrigger;
+	private readonly logger = new DefaultLogger();
+	private httpServer: HonoServer | null = null;
+
+	constructor() {
+		this.trigger = new WebSocketTrigger(this.app);
+
+		const nodeMap = new NodeMap();
+		for (const [key, node] of Object.entries(nodes)) {
+			nodeMap.addNode(key, node);
+		}
+		this.trigger.setNodeMap({
+			nodes: nodeMap,
+			workflows: workflows as unknown as Parameters<typeof this.trigger.setNodeMap>[0]["workflows"],
+		});
+
+		// Register WS-triggered workflows in WorkflowRegistry. Same
+		// rationale as SSEServer: \`workflow({...})\` returns a frozen
+		// builder \`{ _blokV2, _config, toJson }\` so the actual trigger
+		// config lives at \`_config.trigger.websocket\`. Tolerate both
+		// shapes so v1 \`Workflow().addTrigger("websocket")\` authoring
+		// also works.
+		const registry = WorkflowRegistry.getInstance();
+		for (const [name, wf] of Object.entries(workflows)) {
+			const w = wf as {
+				name?: string;
+				trigger?: { websocket?: unknown };
+				_config?: { name?: string; trigger?: { websocket?: unknown } };
+			};
+			const triggerCfg = w._config?.trigger ?? w.trigger;
+			if (!triggerCfg?.websocket) continue;
+			const resolvedName = w._config?.name ?? w.name ?? name;
+			if (registry.get(resolvedName)) continue;
+			registry.register({
+				name: resolvedName,
+				source: \`websocket:\${name}\`,
+				workflow: (w._config ?? w) as unknown as Parameters<typeof registry.register>[0]["workflow"],
+			});
+		}
+	}
+
+	async listen(): Promise<void> {
+		await this.trigger.listen();
+		const port = Number(process.env.TRIGGER_WEBSOCKET_PORT || process.env.PORT || 4002);
+		this.httpServer = serve({ fetch: this.app.fetch, port }, () => {
+			this.logger.log(\`WebSocket server listening on http://localhost:\${port}\`);
+		});
+		// Attach WS upgrade listener — WebSocketTrigger sets \`injectWebSocket\`
+		// as a private field inside listen(); when no httpTrigger is provided
+		// to its constructor, the caller must invoke this on the http.Server
+		// after serve() returns.
+		const triggerWithInternals = this.trigger as unknown as {
+			injectWebSocket?: (server: unknown) => void;
+		};
+		if (typeof triggerWithInternals.injectWebSocket === "function" && this.httpServer) {
+			triggerWithInternals.injectWebSocket(this.httpServer);
+		}
+	}
+
+	async stop(): Promise<void> {
+		await this.trigger.stop();
+		this.httpServer?.close();
+	}
+}
+`;
+}
 function replaceBlokImportsInDirectory(dirPath) {
     const files = fsExtra.readdirSync(dirPath, { withFileTypes: true });
     for (const file of files) {
@@ -886,6 +1320,9 @@ function fixRunnerImportPaths(triggerDestDir, triggerKind) {
     else if (triggerKind === "sse") {
         fileFixes.push({ file: `${triggerDestDir}/SSETrigger.ts`, up: "../../" });
     }
+    else if (triggerKind === "websocket") {
+        fileFixes.push({ file: `${triggerDestDir}/WebSocketTrigger.ts`, up: "../../" });
+    }
     else if (triggerKind === "pubsub") {
         fileFixes.push({ file: `${triggerDestDir}/runner/PubSubServer.ts`, up: "../../../" });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "blokctl",
-	"version": "0.6.4",
+	"version": "0.6.5",
 	"author": "Deskree Technologies Inc.",
 	"license": "Apache-2.0",
 	"description": "cli for blok",
@@ -30,7 +30,7 @@
 	"keywords": ["blokctl", "cli", "blok", "blok"],
 	"dependencies": {
 		"@ai-sdk/openai": "^1.3.22",
-		"@blokjs/runner": "^0.6.4",
+		"@blokjs/runner": "^0.6.5",
 		"@clack/prompts": "^1.0.0",
 		"ai": "^4.3.16",
 		"better-sqlite3": "^12.6.2",