@aurostack/stacks 0.2.0 → 0.2.2

package/cli/stack.mjs

@@ -94,7 +94,7 @@ ${c.bold('extract options')}
 
 ${c.bold('Examples')}
   stack new nest-api ~/Projects/acme/api --with realtime,media
-  stack new react-monorepo ~/Projects/acme/web --without landing
+  stack new react-monorepo ~/Projects/acme/web --with app-landing,app-admin
   stack extract nest-api --source ~/Projects/acme/web/backend
 `;
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aurostack/stacks",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "Scaffold new projects from house templates: a NestJS API, React app or Turborepo monorepo, and Node or Python workers. Subtractive templates plus a zero-dependency generator.",
 	"license": "MIT",
 	"author": "Aurostack (https://github.com/aurostack-org)",

package/templates/nest-api/files/.bin/secrets.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import shell from 'shelljs';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -52,9 +53,7 @@ const getCmd = (env: string) => {
 	if (!PROJECT_ID) {
 		throw new Error('INFISICAL_PROJECT_ID is not set — nothing to fetch from.');
 	}
-	return `infisical export --projectId="${PROJECT_ID}" --path=${SECRET_PATH} --env=${env} > ${getEnvFile(
-		env
-	)}`;
+	return `infisical export --projectId="${PROJECT_ID}" --path=${SECRET_PATH} --env=${env}`;
 };
 
 const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
@@ -62,7 +61,17 @@ const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
 (async () => {
 	const env = await getArg();
 	const command = getCmd(env);
+	const file = getEnvFile(env);
 	log(env);
-	shell.exec(command);
-	process.exit(0);
-})().catch(console.error);
+	// Export first and write only on success: a shell `>` redirect would empty
+	// the existing file before infisical had the chance to fail.
+	const result = shell.exec(command, { silent: true });
+	if (result.code !== 0) {
+		throw new Error(result.stderr.trim() || `infisical exited with ${result.code}`);
+	}
+	fs.writeFileSync(file, result.stdout);
+	console.log(`Wrote ${file}`);
+})().catch((err: unknown) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/templates/nest-api/files/.env.example

@@ -8,7 +8,10 @@ APP_HOST='0.0.0.0'
 PORT='5000'
 SERVER_HOST='http://localhost:5000'
 FRONTEND_HOST='http://localhost:3000'
-# Extra CORS origins beyond FRONTEND_HOST, comma separated.
+# Extra origins beyond FRONTEND_HOST, comma separated: trusted by auth in every
+# environment, allowed by CORS in development only. A full origin
+# (`http://localhost:3001`) is used as written; a bare hostname (`example.com`)
+# expands to https://example.com and its auth., app. and admin. subdomains.
 MISC_CORS_ORIGINS=''
 
 DATABASE_URL='postgresql://root:postgres@localhost:5432/main'
@@ -16,9 +19,13 @@ DATABASE_URL='postgresql://root:postgres@localhost:5432/main'
 # openssl rand -base64 32
 BETTER_AUTH_SECRET='change-me-openssl-rand-base64-32'
 BETTER_AUTH_URL='http://localhost:5000'
-# Leading dot shares the session cookie across subdomains. `.lvh.me` resolves
-# to 127.0.0.1 for every subdomain, which makes local multi-app auth work.
-BETTER_AUTH_COOKIE_DOMAIN='.lvh.me'
+# Empty: the session cookie belongs to the API's own host, which is what
+# localhost development and a single-origin frontend need. Set a parent domain
+# with a leading dot (`.example.com`) when frontends live on subdomains, to share
+# one login across them; locally, `.lvh.me` does the same with `*.lvh.me` hosts
+# (every subdomain resolves to 127.0.0.1). The domain must cover the host the
+# browser talks to, or the cookie is dropped and every sign-in bounces.
+BETTER_AUTH_COOKIE_DOMAIN=''
 BETTER_AUTH_COOKIE_PREFIX='acme'
 
 # Seeded by `yarn db:seed`.

package/templates/nest-api/files/_gitignore

@@ -47,6 +47,7 @@ yarn-error.log
 .env
 .env.test
 .env.production
+.env.staging
 .npmrc
 docker-compose.dev.yaml
 

package/templates/nest-api/files/src/app.module.ts

@@ -81,13 +81,15 @@ import { OriginBuilder } from 'common/misc';
 							ipAddressHeaders: config.rateLimit.ipHeaders
 						},
 						// @feature:end
-						// Share the session cookie across subdomains so one login covers
-						// every frontend. Domain comes from BETTER_AUTH_COOKIE_DOMAIN
-						// (`.lvh.me` in dev, your apex in production).
+						// With BETTER_AUTH_COOKIE_DOMAIN set (`.example.com`), the session
+						// cookie is shared across subdomains so one login covers every
+						// frontend. Empty, it belongs to the API's own host: right for
+						// localhost and for a single-origin frontend. A browser drops a
+						// cookie whose domain doesn't cover the host that set it.
 						cookiePrefix: config.betterAuth.cookiePrefix,
 						crossSubDomainCookies: {
-							enabled: true,
-							domain: config.betterAuth.cookieDomain
+							enabled: Boolean(config.betterAuth.cookieDomain),
+							domain: config.betterAuth.cookieDomain || undefined
 						},
 						database: {
 							joins: true

package/templates/nest-api/files/src/app.setup.ts

@@ -120,9 +120,10 @@ export const enableHelmet = (app: INestApplication) => {
 // @feature:start openapi, queue
 /**
  * Lock the operator-facing surfaces behind basic auth. Every path added here is
- * something that leaks internals if left open — the API reference and the queue
- * dashboard — so a new one belongs in this list on
- * the same commit that mounts it.
+ * something that leaks internals if left open — the API reference (Scalar at
+ * /docs, Swagger UI at /openapi, the raw document at /openapi-json) and the
+ * queue dashboard — so a new one belongs in this list on the same commit that
+ * mounts it.
  */
 export const enableBasicAuth = (app: INestApplication) => {
 	const config = app.get(CustomConfigService);
@@ -131,6 +132,7 @@ export const enableBasicAuth = (app: INestApplication) => {
 	app.use(
 		[
 			'/docs', // @feature openapi
+			'/openapi', // @feature openapi
 			'/openapi-json', // @feature openapi
 			'/dashboard' // @feature queue
 		],

package/templates/nest-api/files/src/common/__tests__/origin-builder.spec.ts

@@ -0,0 +1,24 @@
+import { OriginBuilder } from 'common/misc/origin-builder';
+
+describe('OriginBuilder', () => {
+	it('expands a bare hostname into https origins for it and its subdomains', () => {
+		expect(OriginBuilder.build('example.com')).toEqual([
+			'https://example.com',
+			'https://auth.example.com',
+			'https://app.example.com',
+			'https://admin.example.com'
+		]);
+	});
+
+	it('takes an entry with a scheme as one origin, as written', () => {
+		expect(OriginBuilder.build('http://localhost:3001, http://localhost:3002/')).toEqual([
+			'http://localhost:3001',
+			'http://localhost:3002'
+		]);
+	});
+
+	it('is empty for an empty list', () => {
+		expect(OriginBuilder.build('')).toEqual([]);
+		expect(OriginBuilder.build(undefined)).toEqual([]);
+	});
+});

package/templates/nest-api/files/src/common/constants/pino.ts

@@ -1,3 +1,17 @@
+/**
+ * pino-pretty is a dev dependency, so the production image doesn't have it.
+ * Pretty-print only where it's installed; anywhere else (an image run with an
+ * APP_ENV other than production, say) log JSON to stdout instead of crashing.
+ */
+export const PRETTY_AVAILABLE = (() => {
+	try {
+		require.resolve('pino-pretty');
+		return true;
+	} catch {
+		return false;
+	}
+})();
+
 export const PINO_CONSOLE_TARGET = {
 	target: 'pino-pretty',
 	options: {

package/templates/nest-api/files/src/common/misc/origin-builder.ts

@@ -1,7 +1,9 @@
 /**
- * Builds a list of origins for CORS configuration, given a list of hostnames.
- * Each hostname will generate the main domain and subdomains
- * for app, auth, and admin.
+ * Builds a list of origins for CORS configuration from a list of entries.
+ * A bare hostname (`shop.example.com`) generates https origins for it and its
+ * app, auth and admin subdomains. An entry with a scheme
+ * (`http://localhost:3001`) is taken as one origin, as written: that is how
+ * frontends on other local ports are allowed.
  *
  * @remarks This is mainly for development purposes
  * For frontend developers on the team who cannot run a standalone
@@ -28,6 +30,7 @@ export class OriginBuilder {
 	 * Origins for a single hostname: the main domain plus each subdomain.
 	 */
 	fromHost(hostname: string): string[] {
+		if (hostname.includes('://')) return [hostname.replace(/\/+$/, '')];
 		return [
 			`${this.protocol}${hostname}`,
 			...this.subdomains.map((sub) => `${this.protocol}${sub}.${hostname}`)

package/templates/nest-api/files/src/common/modules/logger.module.ts

@@ -7,7 +7,8 @@ import { LoggerService } from '../services';
 import {
 	PINO_CONSOLE_TARGET,
 	PINO_FILE_TARGET,
-	PINO_CONSOLE_TARGET_PROD
+	PINO_CONSOLE_TARGET_PROD,
+	PRETTY_AVAILABLE
 } from '../constants';
 
 @Global()
@@ -23,7 +24,7 @@ import {
 				pinoHttp: {
 					level: config.logger.level,
 					transport:
-						config.app.env === 'production'
+						config.app.env === 'production' || !PRETTY_AVAILABLE
 							? { targets: [PINO_CONSOLE_TARGET_PROD, PINO_FILE_TARGET] }
 							: { targets: [PINO_CONSOLE_TARGET, PINO_FILE_TARGET] },
 					autoLogging: {

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

@@ -172,7 +172,7 @@ namespace Config {
 		DATABASE_URL: str(),
 		BETTER_AUTH_SECRET: str(),
 		BETTER_AUTH_URL: str(),
-		BETTER_AUTH_COOKIE_DOMAIN: str(),
+		BETTER_AUTH_COOKIE_DOMAIN: z.string().default(''),
 		BETTER_AUTH_COOKIE_PREFIX: str(),
 		SUPERUSER_EMAIL: str(),
 		SUPERUSER_PASSWORD: str(),

package/templates/nest-api/files/src/lib/auth.ts

@@ -33,8 +33,8 @@ export const auth = betterAuth({
 		// sessions through this one, so a different cookie name would reject them.
 		cookiePrefix: env.BETTER_AUTH_COOKIE_PREFIX,
 		crossSubDomainCookies: {
-			enabled: true,
-			domain: env.BETTER_AUTH_COOKIE_DOMAIN
+			enabled: Boolean(env.BETTER_AUTH_COOKIE_DOMAIN),
+			domain: env.BETTER_AUTH_COOKIE_DOMAIN || undefined
 		},
 		database: {
 			joins: true

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

@@ -2,7 +2,7 @@ import { Injectable, NotFoundException } from '@nestjs/common';
 import { NotificationType, Prisma } from '@db/client';
 import { PrismaService, LoggerService } from 'common/services';
 import { ok } from 'common/entity';
-import { RealtimeService } from 'realtime/services/realtime.service';
+import { RealtimeService } from 'realtime/services/realtime.service'; // @feature realtime
 import {
 	NotificationEntity,
 	PaginatedNotificationEntity,
@@ -14,7 +14,7 @@ import { NotificationFilters } from '../dto';
 export class NotificationsService {
 	constructor(
 		private readonly db: PrismaService,
-		private readonly realtime: RealtimeService,
+		private readonly realtime: RealtimeService, // @feature realtime
 		private readonly logger: LoggerService
 	) {}
 
@@ -36,9 +36,11 @@ export class NotificationsService {
 			const notification = await this.db.notification.create({
 				data: { userId, type, data }
 			});
+			// @feature:start realtime
 			// Sockets bypass the HTTP serializer; encode through the same schema so
 			// the event has exactly the shape the REST endpoints return.
 			this.realtime.notifyUser(userId, NotificationEntity.parse(notification));
+			// @feature:end
 			return notification;
 		} catch (err) {
 			this.logger.warn(

package/templates/nest-api/template.json

@@ -47,6 +47,12 @@
 			"regex": true,
 			"flags": "gm"
 		},
+		{
+			"from": "^(SERVER_HOST|BETTER_AUTH_URL)='http://localhost:5000'$",
+			"to": "$1='http://localhost:{{port}}'",
+			"regex": true,
+			"flags": "gm"
+		},
 		{
 			"from": "^EXPOSE 5000$",
 			"to": "EXPOSE {{port}}",
@@ -171,6 +177,9 @@
 		"observability": {
 			"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.",
+			"requires": [
+				"http-client"
+			],
 			"default": true,
 			"files": [
 				"src/common/controllers/health.controller.ts",
@@ -217,10 +226,11 @@
 		"media": {
 			"title": "File uploads (S3)",
 			"description": "MediaService and S3Service for public and private uploads, with multipart decorators.",
-			"default": true,
 			"requires": [
-				"auth"
+				"auth",
+				"queue"
 			],
+			"default": true,
 			"files": [
 				"src/media/**",
 				"src/users/dto/avatar.dto.ts"
@@ -276,7 +286,7 @@
 		},
 		"notifications": {
 			"title": "Persistent user notifications",
-			"description": "A Notification model plus dispatch/read endpoints. Emits over the realtime layer when that feature is also on, and persists either way.",
+			"description": "A Notification model plus dispatch/read endpoints. Pushes each new notification over the realtime layer when that feature is also on, and persists either way.",
 			"requires": [
 				"auth"
 			],
@@ -291,7 +301,8 @@
 			"description": "A session-aware FeatureFlagGuard and FeatureFlagService for gating routes on flags.",
 			"requires": [
 				"cache",
-				"auth"
+				"auth",
+				"scheduler"
 			],
 			"files": [
 				"src/common/services/feature-flag.service.ts",
@@ -408,6 +419,9 @@
 		"ci": {
 			"title": "Forgejo Actions CI",
 			"description": "A workflow that spins up the test stack and runs both Vitest projects on pull requests.",
+			"requires": [
+				"secrets"
+			],
 			"default": true,
 			"files": [
 				".forgejo/**"

package/templates/node-worker/files/.bin/secrets.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import shell from 'shelljs';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -52,9 +53,7 @@ const getCmd = (env: string) => {
 	if (!PROJECT_ID) {
 		throw new Error('INFISICAL_PROJECT_ID is not set — nothing to fetch from.');
 	}
-	return `infisical export --projectId="${PROJECT_ID}" --path=${SECRET_PATH} --env=${env} > ${getEnvFile(
-		env
-	)}`;
+	return `infisical export --projectId="${PROJECT_ID}" --path=${SECRET_PATH} --env=${env}`;
 };
 
 const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
@@ -62,7 +61,17 @@ const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
 (async () => {
 	const env = await getArg();
 	const command = getCmd(env);
+	const file = getEnvFile(env);
 	log(env);
-	shell.exec(command);
-	process.exit(0);
-})().catch(console.error);
+	// Export first and write only on success: a shell `>` redirect would empty
+	// the existing file before infisical had the chance to fail.
+	const result = shell.exec(command, { silent: true });
+	if (result.code !== 0) {
+		throw new Error(result.stderr.trim() || `infisical exited with ${result.code}`);
+	}
+	fs.writeFileSync(file, result.stdout);
+	console.log(`Wrote ${file}`);
+})().catch((err: unknown) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/templates/node-worker/files/_gitignore

@@ -37,6 +37,7 @@ lerna-debug.log*
 .env
 .env.test
 .env.production
+.env.staging
 .npmrc
 docker-compose.dev.yaml
 

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

@@ -72,6 +72,7 @@
 		"@types/node": "^26.1.0",
 		"@types/shelljs": "^0.10.0",
 		"@types/yargs": "^17.0.35",
+		"dotenv-cli": "^7.2.1",
 		"eslint": "^10.6.0",
 		"eslint-config-prettier": "^10.1.8",
 		"globals": "^17.7.0",

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

@@ -2,19 +2,42 @@ import logger from '#app/logger.js';
 import * as Workers from '#app/workers/index.js'; // @feature queue
 import { createTemporalWorker } from '#app/temporal/worker.js'; // @feature temporal
 
-(() => {
-	logger.info('Worker started');
-	void Workers.example.run(); // @feature queue
-	// @feature:start temporal
-	// Temporal handles SIGINT/SIGTERM itself: it stops polling and lets the
-	// current tasks finish. Exit once it has, or open queue connections would
-	// keep the process alive.
-	createTemporalWorker()
-		.then((worker) => worker.run())
-		.then(() => process.exit(0))
-		.catch((err: unknown) => {
-			logger.fatal({ err }, 'Temporal worker failed');
-			process.exit(1);
-		});
-	// @feature:end
-})();
+// Everything still running when a shutdown starts: each entry settles once its
+// worker has stopped taking new work and finished what it had.
+const running: Promise<unknown>[] = [];
+
+logger.info('Worker started');
+
+// @feature:start queue
+// Add each new BullMQ worker to this list: it is started here and closed on
+// shutdown (close() stops fetching and waits for the active job).
+const queueWorkers = [Workers.example];
+for (const worker of queueWorkers) void worker.run();
+// @feature:end
+
+// @feature:start temporal
+// Temporal handles SIGINT/SIGTERM itself: it stops polling and lets running
+// tasks finish, and then run() resolves.
+const temporal = createTemporalWorker().then((worker) => worker.run());
+temporal.catch((err: unknown) => {
+	logger.fatal({ err }, 'Temporal worker failed');
+	process.exit(1);
+});
+running.push(temporal);
+// @feature:end
+
+let stopping = false;
+const shutdown = (signal: NodeJS.Signals) => {
+	// `on` rather than `once`, and idempotent: the telemetry preload re-raises
+	// the signal after flushing, and that second delivery must not kill the
+	// process while jobs are still finishing.
+	if (stopping) return;
+	stopping = true;
+	logger.info({ signal }, 'Shutting down');
+	void Promise.allSettled([
+		...queueWorkers.map((worker) => worker.close()), // @feature queue
+		...running
+	]).then(() => process.exit(0));
+};
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

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

@@ -1,3 +1,4 @@
+import { createRequire } from 'node:module';
 import pino, { stdTimeFunctions, levels } from 'pino';
 import config from '#app/config.js';
 
@@ -26,10 +27,22 @@ const PINO_CONSOLE_TARGET_PROD = {
 	}
 };
 
+// pino-pretty is a dev dependency, so the production image doesn't have it.
+// Pretty-print only where it's installed; anywhere else (an image run with an
+// APP_ENV other than production, say) log JSON to stdout instead of crashing.
+const prettyAvailable = (() => {
+	try {
+		createRequire(import.meta.url).resolve('pino-pretty');
+		return true;
+	} catch {
+		return false;
+	}
+})();
+
 const logger = pino({
 	level: config.app.logLevel,
 	transport:
-		config.app.env === 'production'
+		config.app.env === 'production' || !prettyAvailable
 			? { targets: [PINO_CONSOLE_TARGET_PROD, PINO_FILE_TARGET] }
 			: { targets: [PINO_CONSOLE_TARGET, PINO_FILE_TARGET] },
 	base: {

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

@@ -14,7 +14,7 @@ export const createWorker = <
 	const connection = {
 		host: config.redis.host,
 		port: config.redis.port,
-		user: config.redis.user,
+		username: config.redis.user,
 		password: config.redis.password
 	};
 

package/templates/py-worker/files/utils/db.py

@@ -1,37 +1,22 @@
 """
-@File: db.py
-@Version: 1.0
+Database access over SQLAlchemy, with the connection settings from config
+(DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME).
 
-Database wrapper to manage PostgreSQL connections using SQLAlchemy
+Usage:
 
-DB('my_database') will create a connection to the specified PostgreSQL database
-using credentials from the .env file (user, password, host, port).
+from utils.db import DB
 
-Usage example:
-
-from utils import DB
-
-db = DB('my_database')
-
-# Read data
-df = db.read_sql('SELECT * FROM my_table')
-
-# Write data
-db.write_sql(df, 'my_table', if_exists='append')
-
-# Use engine or session without having to create a new connection or variable
-db.session.query(...)
-db.engine.execute(...)
-# ... perform operations ...
+db = DB()
+rows = db.session.execute(select(MyModel)).scalars().all()
 db.session.commit()
-
-# Close the connection when done
 db.close()
 
+The models under models/ are hand-written to match the API's Prisma schema:
+the API owns the tables and their migrations.
 """
 
 from sqlalchemy import create_engine
-from sqlalchemy.engine import Connection
+from sqlalchemy.engine import URL, Connection
 from sqlalchemy.orm import sessionmaker, Session
 
 from config import CONFIG
@@ -40,9 +25,17 @@ from config import CONFIG
 class DB:
     def __init__(self):
         db = CONFIG.env.db
-        self._engine = create_engine(
-            f"postgresql://{db.user}:{db.password}@{db.host}:{db.port}/{db.name}"
-        ).connect()
+        # URL.create escapes the credentials, so a password with @, / or : in it
+        # can't break the connection string.
+        url = URL.create(
+            "postgresql",
+            username=db.user,
+            password=db.password,
+            host=db.host,
+            port=db.port,
+            database=db.name,
+        )
+        self._engine = create_engine(url).connect()
         Session = sessionmaker(bind=self.engine)
         self._session = Session()
 

package/templates/py-worker/files/utils/logger.py

@@ -2,7 +2,8 @@
 @File: logger.py
 @Version: 1.1
 
-Logger wrapper to manage logs in one place with log rotate
+Logger wrapper to manage logs in one place with log rotate. Records also go to
+stdout, so `docker logs` shows them.
 
 Logger('daily') will create daily.log file in the logs folder
 Logger('my.daily') will create my.daily.log file in the logs folder
@@ -35,6 +36,7 @@ except Exception as e:
 import logging
 import os
 import pathlib
+import sys
 from logging import handlers
 
 from config import CONFIG
@@ -49,7 +51,7 @@ class Logger(object):
         if module is not None:
             directory = f"{directory}/{module}"
             logger_name = f"{module}_{name}"
-            pathlib.Path(directory).mkdir(parents=True, exist_ok=True)
+        pathlib.Path(directory).mkdir(parents=True, exist_ok=True)
 
         filename = f"{directory}/{name}.log"
         formatter = "%(asctime)s %(levelname)-10s %(message)s"
@@ -74,6 +76,11 @@ class Logger(object):
             handler.setFormatter(formatter)
             self.logger.addHandler(handler)
 
+            console = logging.StreamHandler(sys.stdout)
+            console.setLevel(logging.INFO)
+            console.setFormatter(formatter)
+            self.logger.addHandler(console)
+
     def debug(self, message, exc_info=None):
         self.__call(self.logger.debug, message, exc_info)
 

package/templates/py-worker/files/utils/worker.py

@@ -3,7 +3,7 @@ from bullmq import Worker, Job
 from urllib.parse import urlparse, quote, urlencode
 
 from config import CONFIG, Redis
-from utils.db import DB
+from utils.db import DB  # @feature database
 from utils.logger import Logger
 from utils.telemetry import job_span  # @feature telemetry
 
@@ -84,7 +84,7 @@ class JobUtil:
             await self._job.updateProgress(progress)
         await self._job.log(message)
 
-    async def finalize(self, db: DB | None = None):
+    async def finalize(self, db: "DB | None" = None):
         if db:
             db.close()
         await self._job.updateProgress(100)

package/templates/react-app/files/.bin/secrets.js

@@ -1,4 +1,5 @@
 import { execSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
 
 // Pulls this app's env from Infisical into the matching .env file.
 //
@@ -42,6 +43,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${SECRET_PATH}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${SECRET_PATH}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-app/files/.forgejo/workflows/build-and-push.yml

@@ -47,6 +47,9 @@ jobs:
             VITE_APP_API_URL=${{ secrets.VITE_APP_API_URL }}
             VITE_APP_SITE_URL=${{ secrets.VITE_APP_SITE_URL }}
             VITE_APP_SUPPORT_EMAIL=${{ secrets.VITE_APP_SUPPORT_EMAIL }}
+            VITE_OPENOBSERVE_URL=${{ secrets.VITE_OPENOBSERVE_URL }} # @feature telemetry
+            VITE_OPENOBSERVE_ORG=${{ secrets.VITE_OPENOBSERVE_ORG }} # @feature telemetry
+            VITE_OPENOBSERVE_CLIENT_TOKEN=${{ secrets.VITE_OPENOBSERVE_CLIENT_TOKEN }} # @feature telemetry
           tags: |
             ${{ secrets.REGISTRY }}/${{ steps.tag.outputs.OWNER }}/web:latest
             ${{ secrets.REGISTRY }}/${{ steps.tag.outputs.OWNER }}/web:${{ steps.tag.outputs.TAG }}

package/templates/react-app/files/Dockerfile

@@ -35,6 +35,16 @@ ARG VITE_APP_SUPPORT_EMAIL
 ENV VITE_APP_API_URL=$VITE_APP_API_URL \
 	VITE_APP_SITE_URL=$VITE_APP_SITE_URL \
 	VITE_APP_SUPPORT_EMAIL=$VITE_APP_SUPPORT_EMAIL
+# @feature:start telemetry
+# Browser monitoring. Leave unset and the bundle ships with telemetry off. The
+# client token is a RUM token, write-only and meant to be public.
+ARG VITE_OPENOBSERVE_URL
+ARG VITE_OPENOBSERVE_ORG
+ARG VITE_OPENOBSERVE_CLIENT_TOKEN
+ENV VITE_OPENOBSERVE_URL=$VITE_OPENOBSERVE_URL \
+	VITE_OPENOBSERVE_ORG=$VITE_OPENOBSERVE_ORG \
+	VITE_OPENOBSERVE_CLIENT_TOKEN=$VITE_OPENOBSERVE_CLIENT_TOKEN
+# @feature:end
 
 # Fail loudly rather than silently producing a bundle with `undefined` URLs baked
 # in — that failure is invisible until the app 404s at runtime.

package/templates/react-app/files/_gitignore

@@ -22,6 +22,7 @@ dev-dist/
 .env.*.local
 .env.test
 .env.production
+.env.staging
 
 # editor / os
 .DS_Store

package/templates/react-app/files/build.sh

@@ -38,7 +38,9 @@ read_var() {
 }
 
 BUILD_ARGS=""
-for VAR in VITE_APP_API_URL VITE_APP_SITE_URL VITE_APP_SUPPORT_EMAIL; do
+VARS="VITE_APP_API_URL VITE_APP_SITE_URL VITE_APP_SUPPORT_EMAIL"
+VARS="$VARS VITE_OPENOBSERVE_URL VITE_OPENOBSERVE_ORG VITE_OPENOBSERVE_CLIENT_TOKEN" # @feature telemetry
+for VAR in $VARS; do
 	VALUE="$(read_var "$VAR")"
 	[ -n "$VALUE" ] && BUILD_ARGS="$BUILD_ARGS --build-arg $VAR=$VALUE"
 done

package/templates/react-app/template.json

@@ -127,7 +127,7 @@
 		},
 		"pwa": {
 			"title": "Installable PWA",
-			"description": "vite-plugin-pwa: app-shell offline caching and an update prompt rather than a silent takeover.",
+			"description": "vite-plugin-pwa: app-shell offline caching, and registerType 'prompt' so a new build waits for the user instead of swapping assets under a running app. The update prompt and install button are yours to build with the plugin's useRegisterSW.",
 			"packageJson": {
 				"devDependencies": [
 					"vite-plugin-pwa"
@@ -136,7 +136,7 @@
 		},
 		"charts": {
 			"title": "Charts",
-			"description": "ApexCharts via react-apexcharts, theme-aware through the shared chart palette.",
+			"description": "ApexCharts and react-apexcharts, with a theme-aware chart palette (the --chart-* tokens in the UI kit). No chart components ship.",
 			"packageJson": {
 				"dependencies": [
 					"apexcharts",

package/templates/react-monorepo/files/.forgejo/workflows/build-and-push.yml

@@ -1,12 +1,11 @@
-# Builds and pushes all four frontend apps from one Dockerfile.
+# Builds and pushes every app's image from one Dockerfile.
 #
-# Unlike web-backend / web-coming-soon this repo produces FOUR images, so the
-# tag is generated once in a separate job and shared by every matrix leg —
+# The tag is generated once in a separate job and shared by every matrix leg;
 # otherwise each app would get its own random tag and there would be no way to
 # deploy a matching set.
 #
 # Vite compiles the VITE_* URLs into each bundle at build time, so these images
-# are specific to one environment. See frontend/docker/README.md.
+# are specific to one environment.
 
 name: Build and Push
 
@@ -33,12 +32,10 @@ jobs:
           DATE=$(date +'%y_%m_%d')
           RAND=$(printf '%05d' "$((RANDOM % 100000))")
           echo "TAG=${DATE}_${RAND}" >> "$GITHUB_OUTPUT"
-          # Derived from `github.repository` (which web-backend's workflow already
-          # relies on) rather than `github.repository_owner`, so this doesn't
-          # depend on a context variable Forgejo may not populate. This repo is
-          # `acme-corp/web-frontend`, so OWNER=acme-corp and the
-          # images land as <registry>/acme-corp/web-<app>, matching
-          # stack/frontend.compose.yml.
+          # Derived from `github.repository` rather than
+          # `github.repository_owner`, so this doesn't depend on a context
+          # variable Forgejo may not populate. Images land as
+          # <registry>/<owner>/web-<app>.
           echo "OWNER=$(echo '${{ github.repository }}' | cut -d/ -f1)" >> "$GITHUB_OUTPUT"
 
   build-and-push:
@@ -49,7 +46,11 @@ jobs:
       # failure. Note this means a partial set can be pushed — re-run the job.
       fail-fast: false
       matrix:
-        app: [landing, auth, client, admin]
+        app:
+          - landing # @feature app-landing
+          - auth # @feature app-auth
+          - client # @feature app-client
+          - admin # @feature app-admin
 
     steps:
       - name: Checkout repository
@@ -83,6 +84,9 @@ jobs:
             VITE_APP_LANDING=${{ secrets.VITE_APP_LANDING }}
             VITE_APP_SUPPORT_EMAIL=${{ secrets.VITE_APP_SUPPORT_EMAIL }}
             VITE_APP_SITE_URL=${{ secrets.VITE_APP_SITE_URL }}
+            VITE_OPENOBSERVE_URL=${{ secrets.VITE_OPENOBSERVE_URL }} # @feature telemetry
+            VITE_OPENOBSERVE_ORG=${{ secrets.VITE_OPENOBSERVE_ORG }} # @feature telemetry
+            VITE_OPENOBSERVE_CLIENT_TOKEN=${{ secrets.VITE_OPENOBSERVE_CLIENT_TOKEN }} # @feature telemetry
           tags: |
             ${{ secrets.REGISTRY }}/${{ needs.meta.outputs.owner }}/web-${{ matrix.app }}:latest
             ${{ secrets.REGISTRY }}/${{ needs.meta.outputs.owner }}/web-${{ matrix.app }}:${{ needs.meta.outputs.tag }}

package/templates/react-monorepo/files/Dockerfile

@@ -9,24 +9,28 @@
 # IMPORTANT: Vite inlines `VITE_*` values into the JS bundle at BUILD time, so a
 # built image is pinned to one environment. The URLs below are build args, not
 # runtime env — setting them in compose does nothing. Build one image per
-# environment, or move to runtime config (see docker/README.md).
+# environment.
 
 # ---------- deps ----------
 # Manifests only, so `yarn install` re-runs solely when a dependency changes.
 FROM aurostack.dev/wesnetech/nodejs:24 AS deps
 WORKDIR /repo
 
+# One line per workspace: every workspace in the project must be here (yarn
+# install --immutable fails on a lockfile naming a missing one), and nothing
+# else (COPY of a missing file fails the build).
 COPY package.json yarn.lock .yarnrc.yml turbo.json ./
-COPY apps/admin/package.json      apps/admin/
-COPY apps/auth/package.json       apps/auth/
-COPY apps/client/package.json     apps/client/
-COPY apps/landing/package.json    apps/landing/
+COPY apps/admin/package.json      apps/admin/ # @feature app-admin
+COPY apps/auth/package.json       apps/auth/ # @feature app-auth
+COPY apps/client/package.json     apps/client/ # @feature app-client
+COPY apps/landing/package.json    apps/landing/ # @feature app-landing
 COPY packages/api/package.json    packages/api/
 COPY packages/auth/package.json   packages/auth/
 COPY packages/config/package.json packages/config/
-COPY packages/hooks/package.json  packages/hooks/
+COPY packages/hooks/package.json  packages/hooks/ # @feature hooks
 COPY packages/layouts/package.json packages/layouts/
-COPY packages/types/package.json  packages/types/
+COPY packages/telemetry/package.json packages/telemetry/ # @feature telemetry
+COPY packages/types/package.json  packages/types/ # @feature types
 COPY packages/ui/package.json     packages/ui/
 
 RUN corepack enable && yarn install --immutable
@@ -56,6 +60,16 @@ ARG VITE_APP_SUPPORT_EMAIL
 # generated sitemap.xml. Must be a build arg — .dockerignore excludes .env, so a
 # local value never reaches the image.
 ARG VITE_APP_SITE_URL
+# @feature:start telemetry
+# Browser monitoring. Leave unset and the bundle ships with telemetry off. The
+# client token is a RUM token, write-only and meant to be public.
+ARG VITE_OPENOBSERVE_URL
+ARG VITE_OPENOBSERVE_ORG
+ARG VITE_OPENOBSERVE_CLIENT_TOKEN
+ENV VITE_OPENOBSERVE_URL=$VITE_OPENOBSERVE_URL \
+	VITE_OPENOBSERVE_ORG=$VITE_OPENOBSERVE_ORG \
+	VITE_OPENOBSERVE_CLIENT_TOKEN=$VITE_OPENOBSERVE_CLIENT_TOKEN
+# @feature:end
 ENV VITE_APP_API_URL=$VITE_APP_API_URL \
 	VITE_APP_AUTH_HOST=$VITE_APP_AUTH_HOST \
 	VITE_APP_CLIENT_HOST=$VITE_APP_CLIENT_HOST \

package/templates/react-monorepo/files/_gitignore

@@ -22,6 +22,7 @@ dist/
 .env.*.local
 .env.test
 .env.production
+.env.staging
 
 # editor / os
 .DS_Store

package/templates/react-monorepo/files/apps/admin/.bin/secrets.js

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +52,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets for '${slug}' (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-monorepo/files/apps/admin/src/app/router.tsx

@@ -1,7 +1,7 @@
 import { Suspense, lazy, type ReactNode } from 'react';
 import { createBrowserRouter } from 'react-router';
-import { ProtectedRoute, signOut, useAuth } from '@acme/auth';
-import { AppShell, AppShellSkeleton, ErrorBoundary, NotFound, RouteFallback } from '@acme/layouts';
+import { RoleRoute, signOut, useAuth } from '@acme/auth';
+import { AppShell, AppShellSkeleton, ErrorBoundary, Forbidden, NotFound, RouteFallback } from '@acme/layouts';
 import { NAV_ITEMS } from './nav';
 import { HomeRoute } from '../routes/home';
 
@@ -15,8 +15,8 @@ const lazyRoute = (element: ReactNode) => <Suspense fallback={<RouteFallback />}
 
 /**
  * The shell reads the session itself rather than taking it as a prop —
- * `ProtectedRoute` has already established the user is authenticated by the
- * time this renders.
+ * `RoleRoute` has already established the user is signed in with an admin role
+ * by the time this renders.
  *
  * `ErrorBoundary` wraps the shell rather than being passed as the route's
  * `errorElement`: it is a plain React error boundary taking `children`, so it
@@ -35,11 +35,15 @@ export const router = createBrowserRouter([
 	{
 		// `fallback` is required and must not be blank: the session round trip is
 		// cross-origin and takes most of a second, and rendering nothing for that
-		// long reads as a broken app.
+		// long reads as a broken app. Signed-out visitors go to the auth app;
+		// signed-in users without an admin role see Forbidden.
+		//
+		// The gate is UI, not security: every endpoint this console calls must
+		// enforce the same role on the API.
 		element: (
-			<ProtectedRoute fallback={<AppShellSkeleton />}>
+			<RoleRoute allow={['admin', 'superuser']} fallback={<AppShellSkeleton />} forbidden={<Forbidden />}>
 				<Shell />
-			</ProtectedRoute>
+			</RoleRoute>
 		),
 		children: [
 			{ index: true, element: <HomeRoute /> },

package/templates/react-monorepo/files/apps/auth/.bin/secrets.js

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +52,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets for '${slug}' (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-monorepo/files/apps/client/.bin/secrets.js

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +52,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets for '${slug}' (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-monorepo/files/apps/client/src/vite-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="vite/client" />
 /// <reference types="vite-plugin-svgr/client" />
-/// <reference types="vite-plugin-pwa/react" />
+/// <reference types="vite-plugin-pwa/react" /> // @feature pwa
 
 interface ImportMetaEnv {
 	VITE_APP_API_URL: string;

package/templates/react-monorepo/files/apps/landing/.bin/secrets.js

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +52,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets for '${slug}' (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-monorepo/files/build.sh

@@ -46,7 +46,9 @@ read_var() {
 }
 
 BUILD_ARGS="--build-arg APP=$APP"
-for VAR in VITE_APP_API_URL VITE_APP_AUTH_HOST VITE_APP_CLIENT_HOST VITE_APP_ADMIN_HOST VITE_APP_LANDING VITE_APP_SUPPORT_EMAIL; do
+VARS="VITE_APP_API_URL VITE_APP_AUTH_HOST VITE_APP_CLIENT_HOST VITE_APP_ADMIN_HOST VITE_APP_LANDING VITE_APP_SUPPORT_EMAIL VITE_APP_SITE_URL"
+VARS="$VARS VITE_OPENOBSERVE_URL VITE_OPENOBSERVE_ORG VITE_OPENOBSERVE_CLIENT_TOKEN" # @feature telemetry
+for VAR in $VARS; do
 	VALUE="$(read_var "$VAR")"
 	[ -n "$VALUE" ] && BUILD_ARGS="$BUILD_ARGS --build-arg $VAR=$VALUE"
 done

package/templates/react-monorepo/files/packages/types/.bin/secrets.js

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +52,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets for '${slug}' (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-monorepo/files/turbo.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://turbo.build/schema.json",
 	"ui": "tui",
-	"globalDependencies": [".env", "tsconfig.base.json"],
+	"globalDependencies": [".env", "packages/config/tsconfig/base.json"],
 	"tasks": {
 		"build": {
 			"dependsOn": ["^build"],

package/templates/react-monorepo/template.json

@@ -145,14 +145,14 @@
 		},
 		"app-admin": {
 			"title": "Admin console",
-			"description": "Role-gated internal console over the same data layer.",
+			"description": "Internal console over the same data layer, gated to the admin and superuser roles in the UI. The API must enforce the role on every endpoint it calls.",
 			"files": [
 				"apps/admin/**"
 			]
 		},
 		"app-landing": {
 			"title": "Marketing site",
-			"description": "Public landing site with a prerender step for static routes.",
+			"description": "Public marketing site: a home page, an SEO route table, and build-time robots.txt, sitemap.xml and security.txt.",
 			"files": [
 				"apps/landing/**"
 			]
@@ -173,7 +173,7 @@
 		},
 		"pwa": {
 			"title": "Installable PWA (client app)",
-			"description": "vite-plugin-pwa: app-shell offline caching, auto-update with an update prompt, and a custom install button.",
+			"description": "vite-plugin-pwa configured for the client app: app-shell offline caching, and registerType 'prompt' so a new build waits for the user instead of swapping assets under a running app. The update prompt and install button are yours to build with the plugin's useRegisterSW.",
 			"requires": [
 				"app-client"
 			],
@@ -186,7 +186,7 @@
 		},
 		"charts": {
 			"title": "Charts (client app)",
-			"description": "ApexCharts via react-apexcharts, theme-aware through the shared chart palette.",
+			"description": "ApexCharts and react-apexcharts in the client app, with a theme-aware chart palette (the --chart-* tokens in the UI kit). No chart components ship.",
 			"requires": [
 				"app-client"
 			],
@@ -239,11 +239,43 @@
 				"apps/*/.bin/**",
 				"packages/types/.bin/**"
 			],
-			"packageJson": {
-				"scripts": [
-					"secrets"
-				]
-			}
+			"packageJson": [
+				{
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/admin/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/auth/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/client/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/landing/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "packages/types/package.json",
+					"scripts": [
+						"secrets"
+					]
+				}
+			]
 		}
 	},
 	"hooks": [