blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/triggers/worker/src/adapters/SQSAdapter.ts

@@ -0,0 +1,314 @@
+/**
+ * SQSAdapter — v0.7 PR 5 — Worker adapter backed by AWS SQS via
+ * `@aws-sdk/client-sqs`. Polls a queue URL (the `queue` field) with
+ * long-polling; processes messages with manual delete (ACK).
+ *
+ * Semantics:
+ *   - **Long polling**: `WaitTimeSeconds=20` by default — minimises
+ *     poll cost. `concurrency` controls how many parallel
+ *     `ReceiveMessage` loops run.
+ *   - **Visibility timeout**: configured via `timeout` (ms → s).
+ *     Messages reappear after this if the worker doesn't delete them.
+ *   - **Retries**: SQS handles retries automatically via redrive
+ *     policy on the queue itself. The adapter doesn't simulate
+ *     retries client-side — set `MaxReceiveCount` on the queue's
+ *     redrive policy and a DLQ via `deadLetterQueue`.
+ *   - **FIFO support**: when the queue URL ends with `.fifo`, the
+ *     adapter passes `MessageGroupId` from `dedupId` or a default.
+ *
+ * Requires `@aws-sdk/client-sqs` as a peer dependency:
+ *
+ *     bun add @aws-sdk/client-sqs
+ *
+ * Environment variables (standard AWS SDK):
+ *   - `AWS_REGION`              — default `us-east-1`.
+ *   - `AWS_ACCESS_KEY_ID`       — credentials (or use a profile).
+ *   - `AWS_SECRET_ACCESS_KEY`
+ *   - `SQS_ENDPOINT_URL`        — for local SQS (LocalStack / ElasticMQ).
+ */
+
+import type { WorkerTriggerOpts } from "@blokjs/helper";
+import { v4 as uuid } from "uuid";
+import type { WorkerAdapter, WorkerJob, WorkerQueueStats } from "../WorkerTrigger";
+
+export interface SQSConfig {
+	region: string;
+	endpoint?: string;
+	waitTimeSeconds: number;
+	maxNumberOfMessages: number;
+}
+
+interface SqsMessage {
+	MessageId?: string;
+	ReceiptHandle?: string;
+	Body?: string;
+	Attributes?: Record<string, string>;
+	MessageAttributes?: Record<string, { StringValue?: string }>;
+}
+
+interface QueueRunner {
+	stop: boolean;
+	loops: number;
+}
+
+interface QueueStatsCounters {
+	completed: number;
+	failed: number;
+	active: number;
+}
+
+export class SQSAdapter implements WorkerAdapter {
+	readonly provider = "sqs" as const;
+	private readonly config: SQSConfig;
+	// biome-ignore lint/suspicious/noExplicitAny: @aws-sdk/client-sqs client + command types are loose.
+	private client: any = null;
+	// biome-ignore lint/suspicious/noExplicitAny: same as above.
+	private commands: any = null;
+	private runners: Map<string, QueueRunner> = new Map();
+	private connected = false;
+	private stats: Map<string, QueueStatsCounters> = new Map();
+
+	constructor(config?: Partial<SQSConfig>) {
+		this.config = {
+			region: config?.region ?? process.env.AWS_REGION ?? "us-east-1",
+			endpoint: config?.endpoint ?? process.env.SQS_ENDPOINT_URL,
+			waitTimeSeconds: config?.waitTimeSeconds ?? 20,
+			maxNumberOfMessages: config?.maxNumberOfMessages ?? 10,
+		};
+	}
+
+	async connect(): Promise<void> {
+		if (this.connected) return;
+		try {
+			// biome-ignore lint/suspicious/noExplicitAny: peer dep
+			const sdk: any = await import("@aws-sdk/client-sqs");
+			this.client = new sdk.SQSClient({ region: this.config.region, endpoint: this.config.endpoint });
+			this.commands = sdk;
+			this.connected = true;
+		} catch (err) {
+			throw new Error(
+				`[blok][sqs] connect failed: ${(err as Error).message}. Install @aws-sdk/client-sqs as a peer dependency: bun add @aws-sdk/client-sqs`,
+			);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		if (!this.connected) return;
+		for (const runner of this.runners.values()) runner.stop = true;
+		// Wait for in-flight loops to drain — up to 500ms each.
+		const drainDeadline = Date.now() + 2000;
+		while (Date.now() < drainDeadline) {
+			let active = 0;
+			for (const r of this.runners.values()) active += r.loops;
+			if (active === 0) break;
+			await new Promise((r) => setTimeout(r, 50));
+		}
+		this.runners.clear();
+		try {
+			this.client?.destroy?.();
+		} catch {
+			/* ignore */
+		}
+		this.client = null;
+		this.connected = false;
+	}
+
+	async process(config: WorkerTriggerOpts, handler: (job: WorkerJob) => Promise<void>): Promise<void> {
+		if (!this.connected) throw new Error("[blok][sqs] not connected. Call connect() first.");
+		const runner: QueueRunner = { stop: false, loops: 0 };
+		this.runners.set(config.queue, runner);
+		this.stats.set(config.queue, { completed: 0, failed: 0, active: 0 });
+		const stats = this.stats.get(config.queue) as QueueStatsCounters;
+
+		const concurrency = Math.max(1, config.concurrency ?? 1);
+		for (let i = 0; i < concurrency; i += 1) {
+			void this.runConsumerLoop(config, handler, runner, stats);
+		}
+	}
+
+	private async runConsumerLoop(
+		config: WorkerTriggerOpts,
+		handler: (job: WorkerJob) => Promise<void>,
+		runner: QueueRunner,
+		stats: QueueStatsCounters,
+	): Promise<void> {
+		runner.loops += 1;
+		try {
+			while (!runner.stop) {
+				let response: { Messages?: SqsMessage[] } = {};
+				try {
+					response = await this.client.send(
+						new this.commands.ReceiveMessageCommand({
+							QueueUrl: config.queue,
+							MaxNumberOfMessages: Math.min(10, this.config.maxNumberOfMessages),
+							WaitTimeSeconds: this.config.waitTimeSeconds,
+							VisibilityTimeout: typeof config.timeout === "number" ? Math.ceil(config.timeout / 1000) : 30,
+							AttributeNames: ["All"],
+							MessageAttributeNames: ["All"],
+						}),
+					);
+				} catch (err) {
+					// Transient — back off briefly then retry.
+					await new Promise((r) => setTimeout(r, 1000));
+					continue;
+				}
+				const messages = response.Messages ?? [];
+				for (const m of messages) {
+					if (runner.stop) break;
+					stats.active += 1;
+					// Tracks whether the message has already been settled via
+					// the WorkerJob API (`complete` / `fail`). Declared OUTSIDE
+					// the try so the catch arm can read it and skip its own
+					// nack/fail bookkeeping when the handler explicitly
+					// settled. Without this flag we'd double-delete the
+					// receipt handle AND a `fail()` call would be silently
+					// overruled by the wrapper deleting the message anyway.
+					// Caught by the real-broker integration test in
+					// `__tests__/integration/sqs-adapter.real-sqs.test.ts`.
+					let settled = false;
+					try {
+						const payloadString = m.Body ?? "";
+						let data: unknown;
+						try {
+							data = payloadString.length > 0 ? JSON.parse(payloadString) : null;
+						} catch {
+							data = payloadString;
+						}
+						const headers: Record<string, string> = {};
+						for (const [k, v] of Object.entries(m.MessageAttributes ?? {})) {
+							if (typeof v.StringValue === "string") headers[k] = v.StringValue;
+						}
+						const job: WorkerJob = {
+							id: m.MessageId ?? `${config.queue}:${uuid()}`,
+							data,
+							headers,
+							queue: config.queue,
+							priority: config.priority ?? 0,
+							attempts: Number.parseInt(m.Attributes?.ApproximateReceiveCount ?? "1", 10) - 1,
+							maxRetries: config.retries ?? 0,
+							createdAt: new Date(),
+							timeout: config.timeout,
+							raw: m,
+							complete: async () => {
+								if (settled) return;
+								if (m.ReceiptHandle) {
+									await this.client.send(
+										new this.commands.DeleteMessageCommand({
+											QueueUrl: config.queue,
+											ReceiptHandle: m.ReceiptHandle,
+										}),
+									);
+								}
+								stats.completed += 1;
+								settled = true;
+							},
+							fail: async (_err: Error) => {
+								if (settled) return;
+								stats.failed += 1;
+								// No DeleteMessage call — visibility timeout
+								// expires and SQS returns the message to the
+								// queue automatically. DLQ takeover happens via
+								// the queue's RedrivePolicy + MaxReceiveCount.
+								settled = true;
+							},
+						};
+						await handler(job);
+						if (!settled && config.ack !== false && m.ReceiptHandle) {
+							await this.client.send(
+								new this.commands.DeleteMessageCommand({ QueueUrl: config.queue, ReceiptHandle: m.ReceiptHandle }),
+							);
+							stats.completed += 1;
+							settled = true;
+						}
+					} catch {
+						if (!settled) {
+							stats.failed += 1;
+							// Leave the message in flight — SQS visibility
+							// timeout expiry returns it to the queue.
+						}
+					} finally {
+						stats.active = Math.max(0, stats.active - 1);
+					}
+				}
+			}
+		} finally {
+			runner.loops -= 1;
+		}
+	}
+
+	async addJob(
+		queue: string,
+		data: unknown,
+		opts?: { priority?: number; delay?: number; retries?: number; timeout?: number; jobId?: string },
+	): Promise<string> {
+		if (!this.connected) throw new Error("[blok][sqs] not connected. Call connect() first.");
+		const messageId = opts?.jobId ?? uuid();
+		const isFifo = queue.endsWith(".fifo");
+		const params: Record<string, unknown> = {
+			QueueUrl: queue,
+			MessageBody: typeof data === "string" ? data : JSON.stringify(data),
+		};
+		if (isFifo) {
+			params.MessageGroupId = opts?.jobId ?? "default";
+			params.MessageDeduplicationId = messageId;
+		}
+		if (typeof opts?.delay === "number" && opts.delay > 0) {
+			// SQS rejects per-message DelaySeconds on FIFO queues (they only
+			// support a queue-level delay). Fail fast with a clear message
+			// instead of letting the SDK surface a cryptic AWS validation error.
+			if (isFifo) {
+				throw new Error(
+					"[blok][sqs] per-message delay is not supported on FIFO queues; set a queue-level DelaySeconds attribute instead.",
+				);
+			}
+			params.DelaySeconds = Math.min(900, Math.ceil(opts.delay / 1000));
+		}
+		const result = await this.client.send(new this.commands.SendMessageCommand(params));
+		return (result.MessageId as string) ?? messageId;
+	}
+
+	async stopProcessing(queue: string): Promise<void> {
+		const runner = this.runners.get(queue);
+		if (runner) runner.stop = true;
+	}
+
+	isConnected(): boolean {
+		return this.connected;
+	}
+
+	async healthCheck(): Promise<boolean> {
+		if (!this.connected) return false;
+		try {
+			// ListQueues is a cheap permission probe.
+			await this.client.send(new this.commands.ListQueuesCommand({ MaxResults: 1 }));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	async getQueueStats(queue: string): Promise<WorkerQueueStats> {
+		const counters = this.stats.get(queue) ?? { completed: 0, failed: 0, active: 0 };
+		let waiting = 0;
+		let delayed = 0;
+		try {
+			const result = await this.client.send(
+				new this.commands.GetQueueAttributesCommand({
+					QueueUrl: queue,
+					AttributeNames: ["ApproximateNumberOfMessages", "ApproximateNumberOfMessagesDelayed"],
+				}),
+			);
+			waiting = Number.parseInt(result.Attributes?.ApproximateNumberOfMessages ?? "0", 10);
+			delayed = Number.parseInt(result.Attributes?.ApproximateNumberOfMessagesDelayed ?? "0", 10);
+		} catch {
+			/* ignore */
+		}
+		return {
+			waiting,
+			active: counters.active,
+			completed: counters.completed,
+			failed: counters.failed,
+			delayed,
+		};
+	}
+}

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

@@ -0,0 +1,111 @@
+/**
+ * v0.7 PR 5 — adapter factory.
+ *
+ * Resolves a `provider` string to a concrete `WorkerAdapter` instance.
+ * Used by the `WorkerTrigger` (to pick the right adapter per workflow
+ * based on `trigger.worker.provider`) and by the `@blokjs/worker-publish`
+ * helper node (to enqueue jobs from any workflow without bundling all
+ * broker clients).
+ *
+ * Provider resolution order:
+ *   1. Explicit `provider` field on the workflow (highest priority).
+ *   2. `BLOK_WORKER_ADAPTER` env var (per Q7 resolution in the plan).
+ *   3. `"in-memory"` fallback (zero-infra default for dev/tests).
+ *
+ * Each adapter beyond `in-memory` lazy-imports its broker SDK on first
+ * use (BullMQ does this today). Workflows that don't use a given
+ * provider don't pay the install or import cost.
+ */
+
+import type { WorkerProvider } from "@blokjs/helper";
+import type { WorkerAdapter } from "../WorkerTrigger";
+import { BullMQAdapter } from "./BullMQAdapter";
+import { InMemoryAdapter } from "./InMemoryAdapter";
+import { KafkaAdapter } from "./KafkaAdapter";
+import { NATSWorkerAdapter } from "./NATSAdapter";
+import { PgBossAdapter } from "./PgBossAdapter";
+import { RabbitMQAdapter } from "./RabbitMQAdapter";
+import { RedisStreamsAdapter } from "./RedisStreamsAdapter";
+import { SQSAdapter } from "./SQSAdapter";
+
+/**
+ * Resolve the effective provider for a workflow. The trigger's
+ * `provider` field always wins; otherwise fall back to the
+ * `BLOK_WORKER_ADAPTER` env var; otherwise `"in-memory"`.
+ */
+export function resolveProvider(provider?: WorkerProvider): WorkerProvider {
+	if (provider) return provider;
+	const envValue = process.env.BLOK_WORKER_ADAPTER;
+	if (envValue && isWorkerProvider(envValue)) return envValue;
+	return "in-memory";
+}
+
+function isWorkerProvider(value: string): value is WorkerProvider {
+	return (
+		value === "in-memory" ||
+		value === "nats" ||
+		value === "bullmq" ||
+		value === "kafka" ||
+		value === "rabbitmq" ||
+		value === "sqs" ||
+		value === "redis" ||
+		value === "pg-boss"
+	);
+}
+
+/**
+ * Construct an adapter for the named provider. Throws a clear error
+ * for unknown names — keeps the schema validation and runtime
+ * behaviour in sync (the Zod enum catches typos at workflow load).
+ */
+export function createWorkerAdapter(provider: WorkerProvider): WorkerAdapter {
+	switch (provider) {
+		case "in-memory":
+			return new InMemoryAdapter();
+		case "nats":
+			return new NATSWorkerAdapter();
+		case "bullmq":
+			return new BullMQAdapter();
+		case "kafka":
+			return new KafkaAdapter();
+		case "rabbitmq":
+			return new RabbitMQAdapter();
+		case "sqs":
+			return new SQSAdapter();
+		case "redis":
+			return new RedisStreamsAdapter();
+		case "pg-boss":
+			return new PgBossAdapter();
+		default: {
+			const exhaustive: never = provider;
+			throw new Error(`[blok][worker] unknown provider "${exhaustive as string}". Check WorkerProviderSchema.`);
+		}
+	}
+}
+
+/**
+ * Process-singleton adapter pool — one instance per provider. The
+ * trigger calls `getOrCreateAdapter("kafka")` once per workflow, and
+ * subsequent workflows on the same provider share the broker
+ * connection. Adapters are connected lazily — `getOrCreateAdapter`
+ * never connects on its own; the caller calls `adapter.connect()`.
+ *
+ * Reset via `_resetAdapterPoolForTests()` between vitest suites.
+ */
+const pool: Map<WorkerProvider, WorkerAdapter> = new Map();
+
+export function getOrCreateAdapter(provider: WorkerProvider): WorkerAdapter {
+	let adapter = pool.get(provider);
+	if (!adapter) {
+		adapter = createWorkerAdapter(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/worker/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * @blokjs/trigger-worker
+ *
+ * Worker-based trigger for Blok workflows.
+ * Supports background job processing with:
+ * - Configurable concurrency per queue
+ * - Automatic retries with exponential backoff
+ * - Job timeouts
+ * - Priority-based job ordering
+ * - Delayed job scheduling
+ * - Queue statistics and monitoring
+ *
+ * Adapters (v0.7+):
+ * - BullMQ        — Redis-backed, ops-style queues (`bullmq` peer dep)
+ * - InMemory      — development / tests (no peer deps)
+ * - NATS          — JetStream durable streams (`nats` peer dep)
+ * - Kafka         — high-throughput streaming (`kafkajs` peer dep)
+ * - RabbitMQ      — reliable enterprise queues (`amqplib` peer dep)
+ * - SQS           — AWS cloud queues (`@aws-sdk/client-sqs` peer dep)
+ * - Redis Streams — when Redis is already in stack (`ioredis` peer dep)
+ * - pg-boss       — no extra infra (`pg-boss` peer dep)
+ *
+ * v0.7+ — pick the adapter per workflow via `trigger.worker.provider`.
+ * `BLOK_WORKER_ADAPTER` env var sets the default. Subclasses can still
+ * set `protected adapter` directly for back-compat with the pre-v0.7
+ * single-adapter pattern.
+ *
+ * @example BullMQ
+ * ```typescript
+ * import { WorkerTrigger, BullMQAdapter } from "@blokjs/trigger-worker";
+ *
+ * class MyWorkerTrigger extends WorkerTrigger {
+ *   protected adapter = new BullMQAdapter({
+ *     host: "localhost",
+ *     port: 6379,
+ *   });
+ *
+ *   protected nodes = myNodes;
+ *   protected workflows = myWorkflows;
+ * }
+ *
+ * const trigger = new MyWorkerTrigger();
+ * await trigger.listen();
+ *
+ * // Dispatch a job
+ * await trigger.dispatch("background-jobs", { userId: "123" }, {
+ *   priority: 10,
+ *   retries: 3,
+ *   delay: 5000, // delay 5 seconds
+ * });
+ * ```
+ *
+ * @example InMemory (development)
+ * ```typescript
+ * import { WorkerTrigger, InMemoryAdapter } from "@blokjs/trigger-worker";
+ *
+ * class DevWorkerTrigger extends WorkerTrigger {
+ *   protected adapter = new InMemoryAdapter();
+ *   protected nodes = myNodes;
+ *   protected workflows = myWorkflows;
+ * }
+ * ```
+ */
+
+// Core exports
+export {
+	WorkerTrigger,
+	WorkerTimeoutError,
+	type WorkerAdapter,
+	type WorkerJob,
+	type WorkerQueueStats,
+} from "./WorkerTrigger";
+
+// Adapters
+export { BullMQAdapter, type BullMQConfig } from "./adapters/BullMQAdapter";
+export { InMemoryAdapter } from "./adapters/InMemoryAdapter";
+export { KafkaAdapter, type KafkaConfig } from "./adapters/KafkaAdapter";
+export { NATSWorkerAdapter, type NATSWorkerConfig } from "./adapters/NATSAdapter";
+export { PgBossAdapter, type PgBossConfig } from "./adapters/PgBossAdapter";
+export { RabbitMQAdapter, type RabbitMQConfig } from "./adapters/RabbitMQAdapter";
+export { RedisStreamsAdapter, type RedisStreamsConfig } from "./adapters/RedisStreamsAdapter";
+export { SQSAdapter, type SQSConfig } from "./adapters/SQSAdapter";
+
+// v0.7 PR 5 — factory + pool. Used by WorkerTrigger and exposed for
+// helper nodes (`@blokjs/worker-publish`) that need to enqueue jobs
+// from any workflow without bundling all broker SDKs.
+export {
+	_resetAdapterPoolForTests,
+	createWorkerAdapter,
+	getOrCreateAdapter,
+	resolveProvider,
+} from "./adapters/factory";
+
+// Re-export types from helper for convenience
+export type { WorkerProvider, WorkerTriggerOpts } from "@blokjs/helper";

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

@@ -0,0 +1,18 @@
+PROJECT_NAME=trigger-worker-server
+PROJECT_VERSION=0.0.1
+WORKFLOWS_PATH=PROJECT_PATH/workflows
+NODES_PATH=PROJECT_PATH/src/nodes
+CONSOLE_LOG_ACTIVE=true
+APP_NAME=blok-worker
+DISABLE_TRIGGER_RUN=false # Set to true to disable trigger run and use this project as a module
+
+# Worker adapter — resolved per-workflow via `trigger.worker.provider`, then
+# BLOK_WORKER_ADAPTER, then `in-memory`. The in-memory adapter is per-process
+# (dev only); for production set a broker (nats / bullmq / rabbitmq / sqs /
+# pg-boss / kafka) here and supply its connection env below.
+BLOK_WORKER_ADAPTER=in-memory
+
+# NATS JetStream (only needed when BLOK_WORKER_ADAPTER=nats)
+# NATS_SERVERS=localhost:4222
+# NATS_STREAM_NAME=blok-worker
+# NATS_TOKEN=your-auth-token

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

@@ -0,0 +1,46 @@
+{
+	"name": "blok-worker-trigger",
+	"version": "0.1.0",
+	"description": "Worker trigger for Blok background job 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-worker": "^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",
+		"nats": "^2.28.0",
+		"uuid": "^11.1.0",
+		"zod": "^3.24.2"
+	},
+	"private": true
+}

package/dist/scaffold-repo/triggers/worker/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/worker/template/src/Workflows.ts

@@ -0,0 +1,8 @@
+import type Workflows from "./runner/types/Workflows";
+import processJob from "./workflows/jobs/process-job";
+
+const workflows: Workflows = {
+	"process-job": processJob,
+};
+
+export default workflows;

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

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

@@ -0,0 +1,34 @@
+import { WorkerTrigger } from "@blokjs/trigger-worker";
+import nodes from "../Nodes";
+import workflows from "../Workflows";
+
+/**
+ * WorkerServer - Concrete Worker trigger implementation
+ *
+ * The adapter is resolved per-workflow via `trigger.worker.provider`, falling
+ * back to the `BLOK_WORKER_ADAPTER` env var, then the zero-infra `in-memory`
+ * adapter. That means a fresh project boots with no broker running.
+ *
+ * To force ONE adapter for EVERY workflow in this process, uncomment one of the
+ * examples below. Note: a hardcoded `this.adapter` OVERRIDES the per-workflow
+ * `provider` / `BLOK_WORKER_ADAPTER` resolution, so prefer leaving it commented
+ * unless you really want a single broker for the whole process.
+ *
+ *   import { NATSWorkerAdapter } from "@blokjs/trigger-worker";
+ *   protected adapter = new NATSWorkerAdapter({
+ *     servers: (process.env.NATS_SERVERS || "localhost:4222").split(","),
+ *   });
+ *
+ *   // Requires `npm install bullmq` (peer dependency).
+ *   import { BullMQAdapter } from "@blokjs/trigger-worker";
+ *   protected adapter = new BullMQAdapter({
+ *     connection: {
+ *       host: process.env.REDIS_HOST || "localhost",
+ *       port: Number(process.env.REDIS_PORT) || 6379,
+ *     },
+ *   });
+ */
+export default class WorkerServer extends WorkerTrigger {
+	protected nodes: Record<string, import("@blokjs/runner").BlokService<unknown>> = nodes;
+	protected workflows: Record<string, import("@blokjs/helper").WorkflowV2Builder> = workflows;
+}