blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/triggers/pubsub/src/adapters/RedisStreamsPubSubAdapter.ts

@@ -0,0 +1,256 @@
+/**
+ * RedisStreamsPubSubAdapter — v0.7 PR 6 — Pub/Sub adapter backed by
+ * Redis Streams via `ioredis`.
+ *
+ * Pub/Sub vs Worker semantics: this adapter uses **distinct consumer
+ * groups per subscriber** so multiple subscribers each receive every
+ * message (fan-out). When `consumerGroup` is explicitly set on the
+ * workflow, all subscribers in the group compete (1 of N gets each).
+ *
+ * Replay cursors (`startFrom`):
+ *   - unset / `"latest"` → `$` (only new messages).
+ *   - `"earliest"` → `0` (replay full retained stream).
+ *   - `{seq: N}` → resume from stream id `N-0`.
+ *   - `{timestamp: ms}` → resume from id `ms-0` (time cursor).
+ * When the consumer group already exists, `startFrom` is applied via
+ * `XGROUP SETID` so a reconnect / second subscribe still repositions it.
+ *
+ * Group lifecycle: an explicit `consumerGroup` (competing-consumer) or
+ * `durable: true` persists the group; an auto-generated fan-out group is
+ * non-durable and torn down (`XGROUP DESTROY`) on unsubscribe/disconnect.
+ *
+ * Requires `ioredis` as a peer dependency.
+ *
+ * Environment variables:
+ *   - `REDIS_HOST` (default `localhost`).
+ *   - `REDIS_PORT` (default `6379`).
+ *   - `REDIS_PASSWORD`.
+ *   - `REDIS_DB`.
+ */
+
+import type { PubSubTriggerOpts } from "@blokjs/helper";
+import { v4 as uuid } from "uuid";
+import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
+
+export interface RedisStreamsPubSubConfig {
+	host: string;
+	port: number;
+	password?: string;
+	db?: number;
+	blockMs: number;
+	count: number;
+}
+
+interface RedisClient {
+	xadd(stream: string, ...args: string[]): Promise<string>;
+	xreadgroup(...args: string[]): Promise<Array<[string, Array<[string, string[]]>]> | null>;
+	xgroup(...args: string[]): Promise<string>;
+	xack(stream: string, group: string, ...ids: string[]): Promise<number>;
+	ping(): Promise<string>;
+	quit(): Promise<string>;
+}
+
+interface ActiveSubscription {
+	stop: () => void;
+	/** non-durable auto fan-out groups are torn down on unsubscribe/disconnect */
+	cleanup: () => Promise<void>;
+}
+
+export class RedisStreamsPubSubAdapter implements PubSubAdapter {
+	readonly provider = "redis-streams" as const;
+	private readonly config: RedisStreamsPubSubConfig;
+	private client: RedisClient | null = null;
+	private subscriptions: Map<string, ActiveSubscription> = new Map();
+	private connected = false;
+	private consumerName = `blok-pubsub-${uuid().slice(0, 8)}`;
+
+	constructor(config?: Partial<RedisStreamsPubSubConfig>) {
+		this.config = {
+			host: config?.host ?? process.env.REDIS_HOST ?? "localhost",
+			port: config?.port ?? Number.parseInt(process.env.REDIS_PORT ?? "6379", 10),
+			password: config?.password ?? process.env.REDIS_PASSWORD,
+			db: config?.db ?? Number.parseInt(process.env.REDIS_DB ?? "0", 10),
+			blockMs: config?.blockMs ?? 5000,
+			count: config?.count ?? 10,
+		};
+	}
+
+	async connect(): Promise<void> {
+		if (this.connected) return;
+		try {
+			// biome-ignore lint/suspicious/noExplicitAny: ioredis is a runtime peer dep.
+			const ioredis: any = await import("ioredis");
+			const IORedis = ioredis.default ?? ioredis.Redis ?? ioredis;
+			this.client = new IORedis({
+				host: this.config.host,
+				port: this.config.port,
+				password: this.config.password,
+				db: this.config.db,
+			}) as RedisClient;
+			await this.client.ping();
+			this.connected = true;
+		} catch (err) {
+			throw new Error(
+				`[blok][pubsub-redis] connect failed: ${(err as Error).message}. Install ioredis as a peer dependency: bun add ioredis`,
+			);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		if (!this.connected) return;
+		for (const sub of this.subscriptions.values()) sub.stop();
+		// Tear down transient fan-out groups while the client is still alive.
+		for (const sub of this.subscriptions.values()) await sub.cleanup();
+		this.subscriptions.clear();
+		try {
+			await this.client?.quit();
+		} catch {
+			/* ignore */
+		}
+		this.client = null;
+		this.connected = false;
+	}
+
+	async subscribe(config: PubSubTriggerOpts, handler: (message: PubSubMessage) => Promise<void>): Promise<void> {
+		if (!this.connected || !this.client) throw new Error("[blok][pubsub-redis] not connected. Call connect() first.");
+		const client = this.client;
+		const stream = config.topic;
+		// Fan-out: each subscriber gets its own group (unique per instance).
+		// Competing-consumer: explicit `consumerGroup` makes all subscribers
+		// share work.
+		const group = config.consumerGroup ?? `blok-fanout-${this.consumerName}-${stream.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+		// An auto-generated fan-out group (no consumerGroup) that is non-durable
+		// is torn down when the subscription stops; an explicit consumerGroup or
+		// `durable: true` persists the group across (re)connects.
+		const transientGroup = config.consumerGroup === undefined && config.durable !== true;
+		const startFrom = config.startFrom;
+		const startId =
+			startFrom === "earliest"
+				? "0"
+				: startFrom === "latest" || startFrom === undefined
+					? "$"
+					: "seq" in startFrom
+						? `${startFrom.seq}-0`
+						: // {timestamp}: stream ids are `<ms>-<seq>`; a bare ms-0 is a valid
+							// id, so the group resumes from that millisecond.
+							`${startFrom.timestamp}-0`;
+
+		try {
+			await client.xgroup("CREATE", stream, group, startId, "MKSTREAM");
+		} catch (err) {
+			if (!/BUSYGROUP/i.test((err as Error).message)) throw err;
+			// Group already exists (reconnect / second subscribe). XGROUP CREATE
+			// keeps the OLD cursor, so an explicit startFrom would be silently
+			// ignored — reposition the existing group with SETID.
+			if (startFrom !== undefined) await client.xgroup("SETID", stream, group, startId);
+		}
+
+		let stopped = false;
+		const sub: ActiveSubscription = {
+			stop: () => {
+				stopped = true;
+			},
+			cleanup: async () => {
+				if (!transientGroup) return;
+				try {
+					await client.xgroup("DESTROY", stream, group);
+				} catch {
+					/* group already gone / connection closing */
+				}
+			},
+		};
+		this.subscriptions.set(`${stream}#${group}`, sub);
+
+		void (async () => {
+			while (!stopped) {
+				let entries: Array<[string, Array<[string, string[]]>]> | null = null;
+				try {
+					entries = await client.xreadgroup(
+						"GROUP",
+						group,
+						this.consumerName,
+						"COUNT",
+						String(this.config.count),
+						"BLOCK",
+						String(this.config.blockMs),
+						"STREAMS",
+						stream,
+						">",
+					);
+				} catch {
+					await new Promise((r) => setTimeout(r, 1000));
+					continue;
+				}
+				if (!entries) continue;
+				for (const [, msgs] of entries) {
+					for (const [id, fields] of msgs) {
+						if (stopped) break;
+						const payload = this.fieldsToObject(fields);
+						const dataString = typeof payload.data === "string" ? payload.data : "";
+						let body: unknown;
+						try {
+							body = dataString.length > 0 ? JSON.parse(dataString) : null;
+						} catch {
+							body = dataString;
+						}
+						const message: PubSubMessage = {
+							id,
+							body,
+							attributes: payload,
+							raw: { id, fields },
+							topic: stream,
+							subscription: group,
+							publishTime: new Date(Number.parseInt(id.split("-")[0] ?? String(Date.now()), 10)),
+							ack: async () => {
+								await client.xack(stream, group, id);
+							},
+							nack: async () => {
+								/* leave unacked — picked up by XAUTOCLAIM */
+							},
+						};
+						try {
+							await handler(message);
+							if (config.ack !== false) await client.xack(stream, group, id);
+						} catch {
+							// Leave unacked — pending entries are visible in XPENDING.
+						}
+					}
+				}
+			}
+		})();
+	}
+
+	private fieldsToObject(fields: string[]): Record<string, string> {
+		const out: Record<string, string> = {};
+		for (let i = 0; i < fields.length; i += 2) out[fields[i]] = fields[i + 1];
+		return out;
+	}
+
+	async unsubscribe(subscription: string): Promise<void> {
+		const sub = this.subscriptions.get(subscription);
+		if (!sub) return;
+		sub.stop();
+		await sub.cleanup();
+		this.subscriptions.delete(subscription);
+	}
+
+	async publish(topic: string, payload: unknown): Promise<void> {
+		if (!this.connected || !this.client) throw new Error("[blok][pubsub-redis] not connected. Call connect() first.");
+		const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+		await this.client.xadd(topic, "*", "data", body);
+	}
+
+	isConnected(): boolean {
+		return this.connected;
+	}
+
+	async healthCheck(): Promise<boolean> {
+		if (!this.connected || !this.client) return false;
+		try {
+			const pong = await this.client.ping();
+			return pong === "PONG";
+		} catch {
+			return false;
+		}
+	}
+}

package/dist/scaffold-repo/triggers/pubsub/src/adapters/factory.ts

@@ -0,0 +1,88 @@
+/**
+ * v0.7 PR 6 — pub/sub adapter factory.
+ *
+ * Resolves a `provider` string to a concrete `PubSubAdapter` instance.
+ * Used by `PubSubTrigger` (per-workflow provider dispatch) and by the
+ * `@blokjs/pubsub-publish` helper.
+ *
+ * Provider resolution order:
+ *   1. Explicit `provider` field on the workflow.
+ *   2. `BLOK_PUBSUB_ADAPTER` env var.
+ *   3. `"nats"` fallback (cheapest infra; matches the v0.7 plan's
+ *      "default for pub/sub" recommendation).
+ *
+ * Each adapter lazy-imports its broker SDK on first use; workflows
+ * that don't use a given provider don't pay the install cost.
+ */
+
+import type { PubSubProvider } from "@blokjs/helper";
+import type { PubSubAdapter } from "../PubSubTrigger";
+import { AWSSNSAdapter } from "./AWSSNSAdapter";
+import { AzureServiceBusAdapter } from "./AzureServiceBusAdapter";
+import { GCPPubSubAdapter } from "./GCPPubSubAdapter";
+import { KafkaPubSubAdapter } from "./KafkaPubSubAdapter";
+import { NATSPubSubAdapter } from "./NATSPubSubAdapter";
+import { RedisStreamsPubSubAdapter } from "./RedisStreamsPubSubAdapter";
+
+export function resolveProvider(provider?: PubSubProvider): PubSubProvider {
+	if (provider) return provider;
+	const envValue = process.env.BLOK_PUBSUB_ADAPTER;
+	if (envValue && isPubSubProvider(envValue)) return envValue;
+	return "nats";
+}
+
+function isPubSubProvider(value: string): value is PubSubProvider {
+	return (
+		value === "nats" ||
+		value === "redis-streams" ||
+		value === "kafka" ||
+		value === "gcp" ||
+		value === "aws" ||
+		value === "azure"
+	);
+}
+
+export function createPubSubAdapter(provider: PubSubProvider): PubSubAdapter {
+	switch (provider) {
+		case "nats":
+			return new NATSPubSubAdapter();
+		case "redis-streams":
+			return new RedisStreamsPubSubAdapter();
+		case "kafka":
+			return new KafkaPubSubAdapter();
+		case "gcp":
+			return new GCPPubSubAdapter();
+		case "aws":
+			return new AWSSNSAdapter();
+		case "azure":
+			return new AzureServiceBusAdapter();
+		default: {
+			const exhaustive: never = provider;
+			throw new Error(`[blok][pubsub] unknown provider "${exhaustive as string}". Check PubSubProviderSchema.`);
+		}
+	}
+}
+
+/**
+ * Process-singleton adapter pool — one instance per provider. The
+ * trigger calls `getOrCreateAdapter("nats")` once per workflow, and
+ * subsequent workflows on the same provider share the broker
+ * connection.
+ */
+const pool: Map<PubSubProvider, PubSubAdapter> = new Map();
+
+export function getOrCreateAdapter(provider: PubSubProvider): PubSubAdapter {
+	let adapter = pool.get(provider);
+	if (!adapter) {
+		adapter = createPubSubAdapter(provider);
+		pool.set(provider, adapter);
+	}
+	return adapter;
+}
+
+export function _resetAdapterPoolForTests(): void {
+	for (const adapter of pool.values()) {
+		void adapter.disconnect?.().catch(() => {});
+	}
+	pool.clear();
+}

package/dist/scaffold-repo/triggers/pubsub/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * @blokjs/trigger-pubsub
+ *
+ * Pub/Sub-based trigger for Blok workflows. Supports 6 providers:
+ *
+ *   - **NATS** (Core + JetStream) — cheapest infra; subject wildcards.
+ *   - **Redis Streams**           — when Redis is already in stack.
+ *   - **Kafka**                   — high-throughput streaming.
+ *   - **GCP Pub/Sub**             — Google Cloud-locked.
+ *   - **AWS SNS+SQS**             — SNS fan-out → SQS queueing.
+ *   - **Azure Service Bus**       — Azure Service Bus.
+ *
+ * v0.7+ — pick the adapter per workflow via `trigger.pubsub.provider`.
+ * `BLOK_PUBSUB_ADAPTER` env var sets the default (falls back to NATS).
+ * Subclasses can still set `protected adapter` directly for back-
+ * compat with the pre-v0.7 single-adapter pattern.
+ *
+ * **Fan-out vs competing-consumer**: omit `consumerGroup` for fan-out
+ * (every subscriber sees every message); set it for competing-consumer
+ * (1 of N within group). One field disambiguates the two semantics.
+ *
+ * @example v0.7 — NATS subject hierarchy with JSON workflow
+ * ```json
+ * {
+ *   "name": "audit-all-order-events",
+ *   "trigger": {
+ *     "pubsub": {
+ *       "provider": "nats",
+ *       "topic": "orders.>",
+ *       "durable": true,
+ *       "startFrom": "earliest"
+ *     }
+ *   },
+ *   "steps": [...]
+ * }
+ * ```
+ */
+
+// Core exports
+export {
+	PubSubTrigger,
+	type PubSubAdapter,
+	type PubSubMessage,
+} from "./PubSubTrigger";
+
+// Adapters
+export { AWSSNSAdapter, type AWSSNSConfig } from "./adapters/AWSSNSAdapter";
+export { AzureServiceBusAdapter, type AzureServiceBusConfig } from "./adapters/AzureServiceBusAdapter";
+export { GCPPubSubAdapter, type GCPPubSubConfig } from "./adapters/GCPPubSubAdapter";
+export { KafkaPubSubAdapter, type KafkaPubSubConfig } from "./adapters/KafkaPubSubAdapter";
+export { NATSPubSubAdapter, type NATSPubSubConfig } from "./adapters/NATSPubSubAdapter";
+export { RedisStreamsPubSubAdapter, type RedisStreamsPubSubConfig } from "./adapters/RedisStreamsPubSubAdapter";
+
+// v0.7 PR 6 — factory + pool used by PubSubTrigger and exposed for
+// helper nodes (`@blokjs/pubsub-publish`).
+export {
+	_resetAdapterPoolForTests,
+	createPubSubAdapter,
+	getOrCreateAdapter,
+	resolveProvider,
+} from "./adapters/factory";
+
+// Re-export types from helper for convenience
+export type {
+	PubSubProvider,
+	PubSubTriggerOpts,
+} from "@blokjs/helper";

package/dist/scaffold-repo/triggers/pubsub/template/.env.example

@@ -0,0 +1,8 @@
+PROJECT_NAME=trigger-pubsub-server
+PROJECT_VERSION=0.0.1
+PORT=4006
+WORKFLOWS_PATH=PROJECT_PATH/workflows
+NODES_PATH=PROJECT_PATH/src/nodes
+CONSOLE_LOG_ACTIVE=true
+APP_NAME=blok-pubsub
+DISABLE_TRIGGER_RUN=false # Set to true to disable trigger run and use this project as a module

package/dist/scaffold-repo/triggers/pubsub/template/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "blok-pubsub-trigger",
+	"version": "0.1.0",
+	"description": "Pub/Sub trigger for Blok workflows",
+	"type": "module",
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"author": "",
+	"license": "MIT",
+	"scripts": {
+		"dev": "bun --watch run src/index.ts",
+		"start": "bun run dist/index.js",
+		"build": "rimraf ./dist && tsc",
+		"test": "vitest run",
+		"test:dev": "vitest"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"rimraf": "^6.1.2",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"dependencies": {
+		"@blokjs/api-call": "^1.4.0",
+		"@blokjs/core": "^1.4.0",
+		"@blokjs/helper": "^1.4.0",
+		"@blokjs/if-else": "^1.4.0",
+		"@blokjs/runner": "^1.4.0",
+		"@blokjs/shared": "^1.4.0",
+		"@blokjs/trigger-pubsub": "^1.4.0",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/exporter-prometheus": "^0.57.2",
+		"@opentelemetry/resources": "^1.30.1",
+		"@opentelemetry/sdk-metrics": "^1.30.1",
+		"@opentelemetry/sdk-trace-base": "^1.30.1",
+		"@opentelemetry/semantic-conventions": "^1.39.0",
+		"uuid": "^11.1.0",
+		"zod": "^3.24.2"
+	},
+	"private": true
+}

package/dist/scaffold-repo/triggers/pubsub/template/src/Nodes.ts

@@ -0,0 +1,20 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ApiCall from "@blokjs/api-call";
+import IfElse from "@blokjs/if-else";
+import { discoverNodes } from "@blokjs/runner";
+import type { NodeBase } from "@blokjs/shared";
+
+// Published nodes (npm) are registered explicitly. Your OWN nodes under
+// 'nodes/<name>/index.ts' are AUTO-DISCOVERED and registered by their
+// defineNode({ name }) — you never edit this file to add a node.
+const here = dirname(fileURLToPath(import.meta.url));
+const local = await discoverNodes(join(here, "nodes"));
+
+// Map keys are cosmetic — the runner registers each node under its own node.name.
+const nodes: { [key: string]: NodeBase } = {};
+for (const node of [ApiCall as unknown as NodeBase, IfElse as unknown as NodeBase, ...local]) {
+	nodes[(node as { name: string }).name] = node;
+}
+
+export default nodes;

package/dist/scaffold-repo/triggers/pubsub/template/src/Workflows.ts

@@ -0,0 +1,8 @@
+import type Workflows from "./runner/types/Workflows";
+import onMessage from "./workflows/messages/on-message";
+
+const workflows: Workflows = {
+	"on-message": onMessage,
+};
+
+export default workflows;

package/dist/scaffold-repo/triggers/pubsub/template/src/index.ts

@@ -0,0 +1,41 @@
+import { DefaultLogger } from "@blokjs/runner";
+import { type Span, metrics, trace } from "@opentelemetry/api";
+import PubSubServer from "./runner/PubSubServer";
+
+export default class App {
+	private pubsubServer: PubSubServer = <PubSubServer>{};
+	protected trigger_initializer = 0;
+	protected initializer = 0;
+	protected tracer = trace.getTracer(
+		process.env.PROJECT_NAME || "trigger-pubsub-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.pubsubServer = new PubSubServer();
+	}
+
+	async run() {
+		this.tracer.startActiveSpan("initialization", async (span: Span) => {
+			await this.pubsubServer.listen();
+			this.initializer = performance.now() - this.initializer;
+
+			this.logger.log(`Pub/Sub 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();
+}

package/dist/scaffold-repo/triggers/pubsub/template/src/runner/PubSubServer.ts

@@ -0,0 +1,39 @@
+import { GCPPubSubAdapter, PubSubTrigger } from "@blokjs/trigger-pubsub";
+import nodes from "../Nodes";
+import workflows from "../Workflows";
+
+/**
+ * PubSubServer - Concrete Pub/Sub trigger implementation
+ *
+ * This server extends the abstract PubSubTrigger and provides:
+ * - A specific adapter (GCP Pub/Sub by default, can be changed to AWS or Azure)
+ * - Node and workflow registries
+ *
+ * To change the provider, replace:
+ * - GCPPubSubAdapter with AWSSNSAdapter or AzureServiceBusAdapter
+ * - Update the adapter configuration accordingly
+ *
+ * @example AWS SNS/SQS
+ * ```typescript
+ * import { AWSSNSAdapter } from "@blokjs/trigger-pubsub";
+ * protected adapter = new AWSSNSAdapter({
+ *   region: process.env.AWS_REGION || "us-east-1",
+ * });
+ * ```
+ *
+ * @example Azure Service Bus
+ * ```typescript
+ * import { AzureServiceBusAdapter } from "@blokjs/trigger-pubsub";
+ * protected adapter = new AzureServiceBusAdapter({
+ *   connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING || "",
+ * });
+ * ```
+ */
+export default class PubSubServer extends PubSubTrigger {
+	protected adapter = new GCPPubSubAdapter({
+		projectId: process.env.GCP_PROJECT_ID || "my-project",
+	});
+
+	protected nodes: Record<string, import("@blokjs/runner").BlokService<unknown>> = nodes;
+	protected workflows: Record<string, import("@blokjs/helper").WorkflowV2Builder> = workflows;
+}

package/dist/scaffold-repo/triggers/pubsub/template/src/runner/types/Workflows.ts

@@ -0,0 +1,7 @@
+import type { WorkflowV2Builder } from "@blokjs/helper";
+
+type Workflows = {
+	[key: string]: WorkflowV2Builder;
+};
+
+export default Workflows;

package/dist/scaffold-repo/triggers/pubsub/template/src/workflows/messages/on-message.ts

@@ -0,0 +1,42 @@
+import { type Handle, node, step, tpl, workflow } from "@blokjs/core";
+
+/**
+ * Example Pub/Sub CONSUMER — fires when a message arrives on the topic.
+ *
+ * The `msg` entry handle is the message payload + metadata:
+ *   - msg.body                 — the message payload
+ *   - msg.params.topic         — topic / subject name
+ *   - msg.params.messageId     — unique message ID
+ *
+ * Defaults to the local NATS broker (`provider: "nats"`) so the trigger is
+ * verifiable end-to-end with zero cloud setup: start NATS, run `blokctl dev`,
+ * then publish (the paired `publish-order` HTTP producer, or `nats pub
+ * orders.placed '{...}'`) and watch this workflow log the message. Switch
+ * `provider` to "gcp" | "aws" | "azure" for a managed broker.
+ *
+ * v2 reliability knobs available as step()'s 4th arg (uncomment to use):
+ *   { idempotencyKey: msg.params.messageId }  — at-most-once delivery semantics
+ *   { retry: { maxAttempts: 3 } }              — retry on transient failures
+ */
+export default workflow(
+	"On Pub/Sub Message",
+	{
+		version: "1.0.0",
+		trigger: { pubsub: { provider: "nats", topic: "orders.placed" } },
+	},
+	(msg) => {
+		const m = msg as Handle<{ body: unknown; params: { topic: string; messageId: string } }>;
+		// @blokjs/log surfaces the run directly in `blokctl dev` output — no
+		// network — so a live `curl produce → broker → consumer` is observable.
+		step(
+			"log-message",
+			node("@blokjs/log"),
+			{
+				level: "info",
+				message: tpl`pubsub consumed a message on ${m.params.topic}`,
+				attrs: { messageId: m.params.messageId, body: m.body },
+			},
+			{ ephemeral: true },
+		);
+	},
+);

package/dist/scaffold-repo/triggers/pubsub/template/src/workflows/publish-order.ts

@@ -0,0 +1,22 @@
+import { http, node, step, workflow } from "@blokjs/core";
+
+/**
+ * Example Pub/Sub PRODUCER — an HTTP endpoint that publishes to the broker.
+ *
+ * `curl -X POST localhost:4000/orders -d '{"id":"o1"}'` publishes the body to
+ * the `orders.placed` topic; the paired `on-pubsub-message` consumer (a
+ * `trigger: { pubsub }` workflow on the same topic) then fires and logs it —
+ * so the full produce → broker → consume loop is verifiable from the scaffold.
+ *
+ * `@blokjs/pubsub-publish` is a HELPER_NODE (always registered) that resolves
+ * the adapter from `provider` (here "nats") → BLOK_PUBSUB_ADAPTER → nats. Only
+ * registered when the project also has an HTTP trigger (this workflow has an
+ * http trigger; a pubsub-only project can't serve the endpoint).
+ */
+export default workflow("Publish Order", { version: "1.0.0", trigger: http.post("/orders") }, (req) => {
+	step("publish", node("@blokjs/pubsub-publish"), {
+		provider: "nats",
+		topic: "orders.placed",
+		payload: req.body,
+	});
+});

package/dist/scaffold-repo/triggers/pubsub/template/tsconfig.json

@@ -0,0 +1,31 @@
+{
+	"ts-node": {
+		"transpileOnly": true
+	},
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "es2022",
+		"moduleResolution": "bundler",
+		"rootDir": "./src",
+		"baseUrl": ".",
+		"paths": {
+			"@nodes/*": ["./src/nodes/*"],
+			"@src/*": ["src/*"]
+		},
+		"allowJs": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"noUnusedLocals": true,
+		"noImplicitReturns": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true
+	},
+	"compileOnSave": true,
+	"include": ["./src", "./src/nodes/**/*.json", "./src/nodes/**/*.md"],
+	"exclude": ["src/nodes/**/test/*.ts", "**/*.test.ts", "node_modules", "dist"]
+}