@aurostack/stacks 0.1.0 → 0.2.0

package/templates/nest-api/files/src/common/services/temporal.service.ts

@@ -0,0 +1,66 @@
+import { Injectable, OnApplicationShutdown } from '@nestjs/common';
+import { Client, Connection, type TLSConfig } from '@temporalio/client';
+import { CustomConfigService } from './config.service';
+import type Config from './config.service';
+
+/**
+ * A Temporal client for starting and querying workflows; a worker (node-worker
+ * or py-worker) polling the same namespace and task queue runs them.
+ *
+ * The connection is lazy: nothing is dialled until the first call, so the API
+ * boots, and serves everything else, while Temporal is unreachable.
+ *
+ * ```ts
+ * const handle = await this.temporal.client.workflow.start('example', {
+ *   taskQueue: this.temporal.taskQueue,
+ *   workflowId: `example-${user.id}`, // one run per id: a natural dedupe key
+ *   args: [{ name: user.name }]
+ * });
+ * const result = await handle.result(); // or return handle.workflowId
+ * ```
+ *
+ * Reach for Temporal over the BullMQ queue when the work spans many steps,
+ * waits (for minutes to months, or on a signal), or must resume exactly where
+ * it stopped after a crash. A fire-and-forget job is still a queue job.
+ */
+@Injectable()
+export class TemporalService implements OnApplicationShutdown {
+	readonly client: Client;
+	/** The default task queue, from TEMPORAL_TASK_QUEUE. */
+	readonly taskQueue: string;
+	private readonly connection: Connection;
+
+	constructor(config: CustomConfigService) {
+		const { address, namespace, taskQueue, tls } = config.temporal;
+		this.connection = Connection.lazy({ address, tls: temporalTls(tls) });
+		this.client = new Client({ connection: this.connection, namespace });
+		this.taskQueue = taskQueue;
+	}
+
+	async onApplicationShutdown() {
+		await this.connection.close();
+	}
+}
+
+/**
+ * mTLS settings from PEM strings; none at all means plaintext (`null`).
+ * Escaped `\n` are unescaped, so a certificate fits on one line of an env
+ * file.
+ */
+export function temporalTls({
+	ca,
+	cert,
+	key
+}: Config.Temporal['tls']): TLSConfig | null {
+	if (!ca && !cert && !key) return null;
+	if (!cert || !key) {
+		throw new Error(
+			'TEMPORAL_TLS_CERT and TEMPORAL_TLS_KEY must be set together'
+		);
+	}
+	const pem = (value: string) => Buffer.from(value.replace(/\\n/g, '\n'));
+	return {
+		...(ca && { serverRootCACertificate: pem(ca) }),
+		clientCertPair: { crt: pem(cert), key: pem(key) }
+	};
+}

package/templates/nest-api/files/src/instrumentation.ts

@@ -0,0 +1,117 @@
+/**
+ * OpenTelemetry bootstrap: traces, logs and metrics over OTLP. main.ts imports
+ * this first, because instrumentation has to patch modules before anything
+ * requires them. Connection settings are in src/telemetry/config.ts; without
+ * them this file does nothing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { resolveTelemetry } from './telemetry/config';
+
+// Nest reads .env later, through ConfigModule; the connection settings are
+// needed now. Already-set variables (Docker, the shell) are never overridden.
+try {
+	process.loadEnvFile();
+} catch {
+	// no .env — the environment is configured some other way
+}
+
+const telemetry = resolveTelemetry();
+
+if (telemetry.enabled) {
+	// Nest 12 and many of its dependencies load as ESM, which require-hooks do
+	// not see; import-in-the-middle lets instrumentations patch those too.
+	register('import-in-the-middle/hook.mjs', pathToFileURL(__filename));
+	start();
+}
+
+function start() {
+	/* eslint-disable @typescript-eslint/no-require-imports */
+	// Required lazily so a project with telemetry off never loads the SDK, and
+	// typed so the compiler still checks every constructor call below.
+	const { NodeSDK } =
+		require('@opentelemetry/sdk-node') as typeof import('@opentelemetry/sdk-node');
+	const { getNodeAutoInstrumentations } =
+		require('@opentelemetry/auto-instrumentations-node') as typeof import('@opentelemetry/auto-instrumentations-node');
+	const { OTLPTraceExporter } =
+		require('@opentelemetry/exporter-trace-otlp-proto') as typeof import('@opentelemetry/exporter-trace-otlp-proto');
+	const { OTLPLogExporter } =
+		require('@opentelemetry/exporter-logs-otlp-proto') as typeof import('@opentelemetry/exporter-logs-otlp-proto');
+	const { OTLPMetricExporter } =
+		require('@opentelemetry/exporter-metrics-otlp-proto') as typeof import('@opentelemetry/exporter-metrics-otlp-proto');
+	const { BatchLogRecordProcessor } =
+		require('@opentelemetry/sdk-logs') as typeof import('@opentelemetry/sdk-logs');
+	const { PeriodicExportingMetricReader } =
+		require('@opentelemetry/sdk-metrics') as typeof import('@opentelemetry/sdk-metrics');
+	const { resourceFromAttributes } =
+		require('@opentelemetry/resources') as typeof import('@opentelemetry/resources');
+	const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } =
+		require('@opentelemetry/semantic-conventions') as typeof import('@opentelemetry/semantic-conventions');
+	const { ExpressLayerType } =
+		require('@opentelemetry/instrumentation-express') as typeof import('@opentelemetry/instrumentation-express');
+	const { PrismaInstrumentation } =
+		require('@prisma/instrumentation') as typeof import('@prisma/instrumentation');
+	/* eslint-enable @typescript-eslint/no-require-imports */
+
+	const { urls, headers } = telemetry;
+	// Explicit URLs always come with their headers; without them the SDK reads
+	// OTEL_EXPORTER_OTLP_* itself.
+	const exporter = (url?: string) => (url && headers ? { url, headers } : {});
+
+	const sdk = new NodeSDK({
+		resource: resourceFromAttributes({
+			[ATTR_SERVICE_NAME]: telemetry.serviceName,
+			[ATTR_SERVICE_VERSION]: packageVersion(),
+			'deployment.environment.name': telemetry.environment
+		}),
+		traceExporter: new OTLPTraceExporter(exporter(urls?.traces)),
+		logRecordProcessors: [
+			new BatchLogRecordProcessor({
+				exporter: new OTLPLogExporter(exporter(urls?.logs))
+			})
+		],
+		metricReaders: [
+			new PeriodicExportingMetricReader({
+				exporter: new OTLPMetricExporter(exporter(urls?.metrics)),
+				exportIntervalMillis:
+					Number(process.env.OTEL_METRIC_EXPORT_INTERVAL) || 60_000
+			})
+		],
+		instrumentations: [
+			getNodeAutoInstrumentations({
+				// Every file read and DNS lookup as a span is noise, not signal.
+				'@opentelemetry/instrumentation-fs': { enabled: false },
+				'@opentelemetry/instrumentation-dns': { enabled: false },
+				'@opentelemetry/instrumentation-net': { enabled: false },
+				// One span per request handler, not one per middleware layer. Express
+				// 5 routes through the `router` package, whose own instrumentation
+				// would add a span for every layer again.
+				'@opentelemetry/instrumentation-express': {
+					ignoreLayersType: [ExpressLayerType.MIDDLEWARE]
+				},
+				'@opentelemetry/instrumentation-router': { enabled: false }
+			}),
+			new PrismaInstrumentation()
+		]
+	});
+	sdk.start();
+
+	// Flush what is buffered on the way out, then let the signal do what it
+	// would have done without a handler.
+	for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+		process.once(signal, () => {
+			sdk.shutdown().finally(() => process.kill(process.pid, signal));
+		});
+	}
+}
+
+function packageVersion(): string | undefined {
+	try {
+		const file = path.join(process.cwd(), 'package.json');
+		return JSON.parse(fs.readFileSync(file, 'utf8')).version;
+	} catch {
+		return undefined;
+	}
+}

package/templates/nest-api/files/src/main.ts

@@ -1,3 +1,5 @@
+// Must stay first: instrumentation patches modules before anything loads them.
+import './instrumentation'; // @feature observability
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from 'app.module';
 import * as setup from './app.setup';
@@ -11,7 +13,7 @@ import * as setup from './app.setup';
 		bufferLogs: true
 	});
 	setup.usePinoLogger(app);
-	setup.enableBasicAuth(app); // @feature openapi, queue, observability
+	setup.enableBasicAuth(app); // @feature openapi, queue
 	setup.enableVersioning(app);
 	setup.setStatic(app);
 	setup.enableJsonBodyParser(app);

package/templates/nest-api/files/src/telemetry/__tests__/config.spec.ts

@@ -0,0 +1,67 @@
+import { resolveTelemetry } from '../config';
+
+describe('resolveTelemetry', () => {
+	const openobserve = {
+		OPENOBSERVE_URL: 'https://o2.example.com/',
+		OPENOBSERVE_ORG: 'acme',
+		OPENOBSERVE_TOKEN: 'o2oi_secret'
+	};
+
+	it('stays off without connection settings', () => {
+		expect(resolveTelemetry({}).enabled).toBe(false);
+	});
+
+	it.each(['OPENOBSERVE_URL', 'OPENOBSERVE_ORG', 'OPENOBSERVE_TOKEN'])(
+		'stays off when %s is missing',
+		(key) => {
+			const env: Record<string, string | undefined> = { ...openobserve };
+			delete env[key];
+			expect(resolveTelemetry(env).enabled).toBe(false);
+		}
+	);
+
+	it('builds the OpenObserve endpoints and org-token auth', () => {
+		const config = resolveTelemetry(openobserve, 'acme-api');
+
+		expect(config.enabled).toBe(true);
+		expect(config.urls).toEqual({
+			traces: 'https://o2.example.com/api/acme/v1/traces',
+			logs: 'https://o2.example.com/api/acme/v1/logs',
+			metrics: 'https://o2.example.com/api/acme/v1/metrics'
+		});
+		expect(config.headers).toEqual({
+			Authorization: `Basic ${Buffer.from('acme:o2oi_secret').toString('base64')}`,
+			'stream-name': 'acme-api'
+		});
+	});
+
+	it('uses OTEL_SERVICE_NAME, APP_ENV and OPENOBSERVE_STREAM', () => {
+		const config = resolveTelemetry({
+			...openobserve,
+			OTEL_SERVICE_NAME: 'billing-api',
+			APP_ENV: 'production',
+			OPENOBSERVE_STREAM: 'api'
+		});
+
+		expect(config.serviceName).toBe('billing-api');
+		expect(config.environment).toBe('production');
+		expect(config.headers?.['stream-name']).toBe('api');
+	});
+
+	it('defers to the standard OTEL_* variables when they are set', () => {
+		const config = resolveTelemetry({
+			...openobserve,
+			OTEL_EXPORTER_OTLP_ENDPOINT: 'https://collector.example.com'
+		});
+
+		expect(config.enabled).toBe(true);
+		expect(config.urls).toBeUndefined();
+		expect(config.headers).toBeUndefined();
+	});
+
+	it('honours OTEL_SDK_DISABLED over everything', () => {
+		expect(
+			resolveTelemetry({ ...openobserve, OTEL_SDK_DISABLED: 'true' }).enabled
+		).toBe(false);
+	});
+});

package/templates/nest-api/files/src/telemetry/config.ts

@@ -0,0 +1,62 @@
+/**
+ * Where telemetry goes, resolved from the environment before anything else
+ * loads (instrumentation runs ahead of Nest, so it cannot use
+ * CustomConfigService — this is the one place that reads process.env for it).
+ *
+ * Two ways to connect, in order of precedence:
+ * - standard OpenTelemetry variables (OTEL_EXPORTER_OTLP_ENDPOINT and friends),
+ *   which the SDK reads itself, for any OTLP backend;
+ * - OPENOBSERVE_URL + OPENOBSERVE_ORG + OPENOBSERVE_TOKEN, from which the
+ *   OpenObserve endpoint and auth header are built.
+ * With neither, telemetry stays off and the SDK is never started.
+ */
+export interface TelemetryConfig {
+	enabled: boolean;
+	serviceName: string;
+	environment: string;
+	/** Signal URLs; undefined means the SDK resolves them from OTEL_* vars. */
+	urls?: { traces: string; logs: string; metrics: string };
+	headers?: Record<string, string>;
+}
+
+type Env = Record<string, string | undefined>;
+
+export function resolveTelemetry(
+	env: Env = process.env,
+	defaultServiceName = 'acme-api'
+): TelemetryConfig {
+	const serviceName = env.OTEL_SERVICE_NAME || defaultServiceName;
+	const environment = env.APP_ENV || 'development';
+	const off = { enabled: false, serviceName, environment };
+
+	if (env.OTEL_SDK_DISABLED === 'true') return off;
+	if (env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+		return { enabled: true, serviceName, environment };
+	}
+
+	const {
+		OPENOBSERVE_URL: url,
+		OPENOBSERVE_ORG: org,
+		OPENOBSERVE_TOKEN: token
+	} = env;
+	if (!url || !org || !token) return off;
+
+	// OTLP/HTTP endpoints live under /api/<org>; an org ingestion token
+	// authenticates as `<org>:<token>`. Logs and traces land in the stream
+	// named here — one per service keeps an API and its workers apart.
+	const base = `${url.replace(/\/+$/, '')}/api/${org}`;
+	return {
+		enabled: true,
+		serviceName,
+		environment,
+		urls: {
+			traces: `${base}/v1/traces`,
+			logs: `${base}/v1/logs`,
+			metrics: `${base}/v1/metrics`
+		},
+		headers: {
+			Authorization: `Basic ${Buffer.from(`${org}:${token}`).toString('base64')}`,
+			'stream-name': env.OPENOBSERVE_STREAM || serviceName
+		}
+	};
+}

package/templates/nest-api/template.json

@@ -104,7 +104,8 @@
 					"bullmq",
 					"@bull-board/api",
 					"@bull-board/express",
-					"@bull-board/nestjs"
+					"@bull-board/nestjs",
+					"bullmq-otel"
 				]
 			}
 		},
@@ -168,23 +169,35 @@
 			"core": true
 		},
 		"observability": {
-			"title": "Metrics and health checks",
-			"description": "A Prometheus /metrics endpoint and Terminus health checks, including a Prisma indicator. Structured pino logging is always included.",
+			"title": "Observability: OpenTelemetry and health checks",
+			"description": "OpenTelemetry traces, logs and metrics pushed over OTLP (built for OpenObserve; set OPENOBSERVE_URL/ORG/TOKEN, or any OTEL_* backend), plus Terminus health checks with a Prisma indicator. Off at runtime until connected.",
 			"default": true,
 			"files": [
-				"src/common/modules/metrics.module.ts",
-				"src/common/controllers/metrics.controller.ts",
 				"src/common/controllers/health.controller.ts",
-				"src/common/interceptors/metrics.interceptor.ts",
 				"src/common/misc/prisma.indicator.ts",
 				"src/common/__tests__/health.controller.spec.ts",
-				"src/common/__tests__/prisma.indicator.spec.ts"
+				"src/common/__tests__/prisma.indicator.spec.ts",
+				"src/instrumentation.ts",
+				"src/telemetry/**"
 			],
 			"packageJson": {
 				"dependencies": [
-					"prom-client",
-					"@willsoto/nestjs-prometheus",
-					"@nestjs/terminus"
+					"@nestjs/terminus",
+					"@opentelemetry/api",
+					"@opentelemetry/core",
+					"@opentelemetry/sdk-node",
+					"@opentelemetry/auto-instrumentations-node",
+					"@opentelemetry/exporter-trace-otlp-proto",
+					"@opentelemetry/exporter-logs-otlp-proto",
+					"@opentelemetry/exporter-metrics-otlp-proto",
+					"@opentelemetry/sdk-logs",
+					"@opentelemetry/sdk-metrics",
+					"@opentelemetry/resources",
+					"@opentelemetry/semantic-conventions",
+					"@opentelemetry/instrumentation",
+					"@opentelemetry/instrumentation-express",
+					"import-in-the-middle",
+					"@prisma/instrumentation"
 				]
 			}
 		},
@@ -290,6 +303,19 @@
 				]
 			}
 		},
+		"temporal": {
+			"title": "Temporal client",
+			"description": "A TemporalService for starting and querying durable workflows (multi-step, long-waiting or crash-resumable work; BullMQ stays for fire-and-forget jobs), plus Temporal's dev server in compose.yml. Pair it with node-worker or py-worker built --with temporal to run the workflows. Connects lazily, so the API runs while Temporal is down.",
+			"files": [
+				"src/common/services/temporal.service.ts",
+				"src/common/__tests__/temporal.service.spec.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@temporalio/client"
+				]
+			}
+		},
 		"graphql": {
 			"title": "GraphQL endpoint",
 			"description": "Code-first GraphQL via Apollo, registered alongside the REST controllers. Resolvers in any feature module are picked up automatically.",
@@ -415,7 +441,7 @@
 		},
 		{
 			"title": "yarn install",
-			"run": "yarn install",
+			"run": "yarn install --no-immutable",
 			"optional": true
 		},
 		{

package/templates/node-worker/files/.env.example

@@ -13,6 +13,33 @@ REDIS_HOST='localhost'
 REDIS_PORT='6379'
 REDIS_USER=''
 REDIS_PASSWORD=''
+# @feature:start telemetry
+
+# OpenTelemetry → OpenObserve: traces, logs and metrics. Leave empty and
+# telemetry stays off. Per project: OPENOBSERVE_ORG is the organization
+# identifier, OPENOBSERVE_TOKEN its ingestion token (IAM → Ingestion Tokens).
+# Any other OTLP backend: set OTEL_EXPORTER_OTLP_ENDPOINT/HEADERS instead.
+OPENOBSERVE_URL='https://o2.aurostack.co'
+OPENOBSERVE_ORG=''
+OPENOBSERVE_TOKEN=''
+OTEL_SERVICE_NAME='collector'
+# @feature:end
+
+# @feature:start temporal
+# Temporal: this process also runs the workflows in src/temporal. Locally, the
+# API's dev server (its compose.yml; UI on http://localhost:8233), no TLS. In
+# production, the server address, the project's namespace and its mTLS client
+# certificate (plus the CA that signed the server's), as PEM. Escaped \n are
+# accepted, so each fits on one line.
+TEMPORAL_ADDRESS='localhost:7233'
+TEMPORAL_NAMESPACE='default'
+# The queue this worker polls; must match where the API starts workflows (its
+# TEMPORAL_TASK_QUEUE). A mismatch is silent: workflows just sit waiting.
+TEMPORAL_TASK_QUEUE='main'
+TEMPORAL_TLS_CA=''
+TEMPORAL_TLS_CERT=''
+TEMPORAL_TLS_KEY=''
+# @feature:end
 
 # @feature:start browser
 # Empty = use Puppeteer's bundled Chromium. Set this in a slim container image

package/templates/node-worker/files/.prettierignore

@@ -2,3 +2,5 @@ node_modules/
 dist/
 tmp/
 yarn.lock
+# the Prisma client is generated; formatting it would only churn
+prisma/generated/

package/templates/node-worker/files/Dockerfile

@@ -1,5 +1,11 @@
 # Stage 1: Build
+# @feature:start temporal
+# Temporal's native core ships glibc builds only (it fails to load on Alpine,
+# even with gcompat), so a Temporal worker builds and runs on Debian.
+FROM node:24-bookworm-slim AS build
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24 AS build
+# @feature:end
 
 # @feature:start browser
 # Chromium comes from apk in the runtime stage; don't download a second copy.
@@ -31,10 +37,25 @@ RUN yarn build
 RUN yarn workspaces focus --all --production
 
 # Stage 2: Production
+# @feature:start temporal
+FROM node:24-bookworm-slim
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24
+# @feature:end
 WORKDIR /app
 
 # @feature:start browser
+# @feature:start temporal
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		chromium \
+		ca-certificates \
+		fonts-freefont-ttf \
+	&& rm -rf /var/lib/apt/lists/*
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
+	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+# @feature:else
 RUN apk add --no-cache \
 	chromium \
 	nss \
@@ -47,6 +68,7 @@ RUN apk add --no-cache \
 ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
 	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 # @feature:end
+# @feature:end
 
 COPY package.json ./
 # @feature:start pm2
@@ -56,8 +78,9 @@ COPY --from=build /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 
 # @feature:start pm2
-# pm2-runtime ships in the base image.
+# pm2-runtime ships in the house base image; Debian's needs it installed.
+RUN npm install -g pm2@7 # @feature temporal
 CMD [ "pm2-runtime", "start", "ecosystem.config.cjs" ]
 # @feature:else
-CMD [ "node", "dist/src/index.js" ]
+CMD [ "node", "--import", "./dist/src/instrumentation.js", "dist/src/index.js" ]
 # @feature:end

package/templates/node-worker/files/Dockerfile.dev

@@ -1,5 +1,11 @@
 # Stage 1: Build
+# @feature:start temporal
+# Temporal's native core ships glibc builds only (it fails to load on Alpine,
+# even with gcompat), so a Temporal worker builds and runs on Debian.
+FROM node:24-bookworm-slim AS build
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24 AS build
+# @feature:end
 
 # @feature:start browser
 # Chromium comes from apk in the runtime stage; don't download a second copy.
@@ -27,10 +33,25 @@ COPY src ./src
 RUN yarn build
 
 # Stage 2: Production
+# @feature:start temporal
+FROM node:24-bookworm-slim
+# @feature:else
 FROM aurostack.dev/wesnetech/nodejs:24
+# @feature:end
 WORKDIR /app
 
 # @feature:start browser
+# @feature:start temporal
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends \
+		chromium \
+		ca-certificates \
+		fonts-freefont-ttf \
+	&& rm -rf /var/lib/apt/lists/*
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
+	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+# @feature:else
 RUN apk add --no-cache \
 	chromium \
 	nss \
@@ -43,6 +64,7 @@ RUN apk add --no-cache \
 ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
 	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 # @feature:end
+# @feature:end
 
 COPY package.json ./
 # @feature:start pm2
@@ -52,8 +74,9 @@ COPY --from=build /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 
 # @feature:start pm2
-# pm2-runtime ships in the base image.
+# pm2-runtime ships in the house base image; Debian's needs it installed.
+RUN npm install -g pm2@7 # @feature temporal
 CMD [ "pm2-runtime", "start", "ecosystem.config.cjs" ]
 # @feature:else
-CMD [ "node", "dist/src/index.js" ]
+CMD [ "node", "--import", "./dist/src/instrumentation.js", "dist/src/index.js" ]
 # @feature:end

package/templates/node-worker/files/ecosystem.config.cjs

@@ -3,6 +3,8 @@ module.exports = {
 		{
 			name: 'collector',
 			script: 'dist/src/index.js',
+			// Preload src/instrumentation.ts (OpenTelemetry) before the worker's modules.
+			node_args: '--import ./dist/src/instrumentation.js',
 			watch: false,
 			autorestart: false,
 		}

package/templates/node-worker/files/package.json

@@ -24,10 +24,10 @@
 		}
 	},
 	"scripts": {
-		"dev": "tsx --conditions=development src/index.ts",
-		"dev:watch": "tsx watch --conditions=development src/index.ts",
+		"dev": "tsx --conditions=development --import ./src/instrumentation.ts src/index.ts",
+		"dev:watch": "tsx watch --conditions=development --import ./src/instrumentation.ts src/index.ts",
 		"build": "tsc",
-		"start": "node dist/src/index.js",
+		"start": "node --import ./dist/src/instrumentation.js dist/src/index.js",
 		"secrets": "tsx --conditions=development .bin/secrets",
 		"db:generate": "tsx --conditions=development ./.bin/db.ts",
 		"typecheck": "tsc --noEmit",
@@ -37,11 +37,30 @@
 		"format:check": "prettier --check ."
 	},
 	"dependencies": {
+		"@opentelemetry/api": "^1.9.1",
+		"@opentelemetry/auto-instrumentations-node": "^0.80.0",
+		"@opentelemetry/core": "^2.11.0",
+		"@opentelemetry/exporter-logs-otlp-proto": "^0.222.0",
+		"@opentelemetry/exporter-metrics-otlp-proto": "^0.222.0",
+		"@opentelemetry/exporter-trace-otlp-proto": "^0.222.0",
+		"@opentelemetry/instrumentation": "^0.222.0",
+		"@opentelemetry/resources": "^2.11.0",
+		"@opentelemetry/sdk-logs": "^0.222.0",
+		"@opentelemetry/sdk-metrics": "^2.11.0",
+		"@opentelemetry/sdk-node": "^0.222.0",
+		"@opentelemetry/semantic-conventions": "^1.43.0",
 		"@paralleldrive/cuid2": "^3.3.0",
 		"@prisma/adapter-pg": "^7.8.0",
 		"@prisma/client": "^7.8.0",
-		"bullmq": "^5.79.2",
+		"@prisma/instrumentation": "^7.10.0",
+		"@temporalio/activity": "^1.24.0",
+		"@temporalio/worker": "^1.24.0",
+		"@temporalio/workflow": "^1.24.0",
+		"bullmq": "^6.3.9",
+		"bullmq-otel": "^2.0.1",
 		"dotenv": "^17.4.2",
+		"import-in-the-middle": "^3.5.1",
+		"ioredis": "^5.4.1",
 		"moment": "^2.30.1",
 		"pino": "^10.3.1",
 		"puppeteer": "^25.3.0",

package/templates/node-worker/files/src/config.ts

@@ -16,6 +16,16 @@ interface Redis {
 	password?: string | undefined;
 }
 
+// @feature:start temporal
+interface Temporal {
+	address: string;
+	namespace: string;
+	taskQueue: string;
+	/** PEM; all empty means plaintext (the local dev server). */
+	tls: { ca: string; cert: string; key: string };
+}
+// @feature:end
+
 // @feature:start browser
 interface Puppeteer {
 	executablePath: string;
@@ -26,6 +36,7 @@ interface Config {
 	app: App;
 	database: Database;
 	redis: Redis;
+	temporal: Temporal; // @feature temporal
 	puppeteer: Puppeteer; // @feature browser
 }
 
@@ -43,6 +54,18 @@ const config: Config = {
 		user: process.env.REDIS_USER,
 		password: process.env.REDIS_PASSWORD
 	},
+	// @feature:start temporal
+	temporal: {
+		address: process.env.TEMPORAL_ADDRESS || 'localhost:7233',
+		namespace: process.env.TEMPORAL_NAMESPACE || 'default',
+		taskQueue: process.env.TEMPORAL_TASK_QUEUE || 'main',
+		tls: {
+			ca: process.env.TEMPORAL_TLS_CA ?? '',
+			cert: process.env.TEMPORAL_TLS_CERT ?? '',
+			key: process.env.TEMPORAL_TLS_KEY ?? ''
+		}
+	},
+	// @feature:end
 	// @feature:start browser
 	// Empty means "let Puppeteer use its bundled Chromium". In a slim container
 	// image you install Chromium separately and point this at it.