@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/common/__tests__/prisma.service.spec.ts

@@ -0,0 +1,15 @@
+import { TestBed } from '@suites/unit';
+import { PrismaService } from 'common/services';
+
+describe('PrismaService', () => {
+	let service: PrismaService;
+
+	beforeAll(async () => {
+		const { unit } = await TestBed.solitary(PrismaService).compile();
+		service = unit;
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+});

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

@@ -0,0 +1,87 @@
+import { BadRequestException } from '@nestjs/common';
+import type { PrismaService } from 'common/services';
+import { ensureEachExists, ensureExists, ensureUnique } from 'common/utils';
+
+describe('record checks', () => {
+	const exists = vi.fn();
+	const db = { x: { user: { exists } } } as unknown as PrismaService;
+
+	beforeEach(() => exists.mockReset());
+
+	describe('ensureExists', () => {
+		it('passes when a row has the value, matching case-insensitively', async () => {
+			exists.mockResolvedValue(true);
+
+			await expect(ensureExists(db, 'user', 'role', 'Admin')).resolves.toBe(
+				undefined
+			);
+			expect(exists).toHaveBeenCalledWith({
+				role: { equals: 'Admin', mode: 'insensitive' }
+			});
+		});
+
+		it('rejects with a validation error when no row has it', async () => {
+			exists.mockResolvedValue(false);
+
+			await expect(ensureExists(db, 'user', 'role', 'ghost')).rejects.toThrow(
+				new BadRequestException("Validation: role 'ghost' does not exist")
+			);
+		});
+
+		it.each([undefined, null, ''])(
+			'skips an empty value (%s)',
+			async (value) => {
+				await ensureExists(db, 'user', 'role', value);
+				expect(exists).not.toHaveBeenCalled();
+			}
+		);
+	});
+
+	describe('ensureEachExists', () => {
+		it('passes when every value exists', async () => {
+			exists.mockResolvedValue(true);
+
+			await ensureEachExists(db, 'user', 'id', ['a', 'b']);
+			expect(exists).toHaveBeenCalledTimes(2);
+		});
+
+		it('names the first value that does not exist', async () => {
+			exists.mockResolvedValueOnce(true).mockResolvedValueOnce(false);
+
+			await expect(
+				ensureEachExists(db, 'user', 'id', ['a', 'b', 'c'])
+			).rejects.toThrow(
+				new BadRequestException(
+					"Validation: id element with id 'b' does not exist"
+				)
+			);
+			expect(exists).toHaveBeenCalledTimes(2);
+		});
+
+		it('skips a missing list', async () => {
+			await ensureEachExists(db, 'user', 'id', undefined);
+			expect(exists).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('ensureUnique', () => {
+		it('passes when no row has the value', async () => {
+			exists.mockResolvedValue(false);
+			await expect(
+				ensureUnique(db, 'user', 'email', 'new@example.com')
+			).resolves.toBe(undefined);
+		});
+
+		it('rejects with a validation error when the value is taken', async () => {
+			exists.mockResolvedValue(true);
+
+			await expect(
+				ensureUnique(db, 'user', 'email', 'taken@example.com')
+			).rejects.toThrow(
+				new BadRequestException(
+					"Validation: email 'taken@example.com' already exists"
+				)
+			);
+		});
+	});
+});

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

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { Prisma } from '@db/client';
+import {
+	dateOnly,
+	dateTime,
+	decimal,
+	email,
+	mustMatch,
+	search,
+	sortKeys
+} from 'common/schemas';
+import { CommonFilters, DateFilters } from 'common/dto';
+
+const messages = (result: { error?: z.ZodError }) =>
+	result.error?.issues.map((issue) => issue.message) ?? [];
+
+describe('schema fields', () => {
+	describe('dateTime', () => {
+		it('serializes a Date as an ISO date-time string', () => {
+			const at = new Date('2026-01-02T03:04:05.678Z');
+			expect(dateTime().parse(at)).toBe('2026-01-02T03:04:05.678Z');
+		});
+
+		it('rejects anything but a Date', () => {
+			expect(dateTime().safeParse('2026-01-02').success).toBe(false);
+		});
+	});
+
+	describe('dateOnly', () => {
+		it('serializes a Date as YYYY-MM-DD', () => {
+			expect(dateOnly().parse(new Date('2026-03-04T23:00:00.000Z'))).toBe(
+				'2026-03-04'
+			);
+		});
+	});
+
+	describe('decimal', () => {
+		it('serializes a Prisma.Decimal as a number, rounded to 4 places', () => {
+			expect(decimal().parse(new Prisma.Decimal('12.345678'))).toBe(12.3457);
+		});
+
+		it('accepts a numeric string', () => {
+			expect(decimal().parse('3.5')).toBe(3.5);
+		});
+	});
+
+	describe('email', () => {
+		it('lower-cases a valid address', () => {
+			expect(email().parse('Ada@Example.COM')).toBe('ada@example.com');
+		});
+
+		it('rejects an invalid address', () => {
+			expect(email().safeParse('not-an-email').success).toBe(false);
+		});
+	});
+
+	describe('search', () => {
+		const schema = z.object({ search: search() });
+
+		it('trims a search of three or more characters', () => {
+			expect(schema.parse({ search: '  kamil ' })).toEqual({ search: 'kamil' });
+		});
+
+		it('treats a blank search as absent', () => {
+			expect(schema.parse({ search: '' })).toEqual({ search: undefined });
+		});
+
+		it('rejects a search shorter than three characters', () => {
+			expect(schema.safeParse({ search: 'ab' }).success).toBe(false);
+		});
+	});
+
+	describe('sortKeys', () => {
+		const sort = sortKeys(['name', 'createdAt']);
+
+		it('accepts allowed keys, with or without a descending prefix', () => {
+			expect(sort.parse('name,-createdAt')).toBe('name,-createdAt');
+		});
+
+		it('is optional', () => {
+			expect(sort.parse(undefined)).toBeUndefined();
+		});
+
+		it('rejects an unknown key and lists the allowed ones', () => {
+			const result = sort.safeParse('name,email');
+			expect(messages(result)).toEqual([
+				'Sort key must be one of the following: name, createdAt'
+			]);
+		});
+	});
+
+	describe('mustMatch', () => {
+		const schema = z
+			.object({ password: z.string(), confirmPassword: z.string() })
+			.superRefine(mustMatch('password', 'confirmPassword'));
+
+		it('passes when the fields match', () => {
+			expect(
+				schema.safeParse({ password: 'a', confirmPassword: 'a' }).success
+			).toBe(true);
+		});
+
+		it('reports a mismatch on the confirming field', () => {
+			const result = schema.safeParse({ password: 'a', confirmPassword: 'b' });
+			expect(result.error?.issues[0].path).toEqual(['confirmPassword']);
+			expect(messages(result)).toEqual(['confirmPassword must match password']);
+		});
+	});
+});
+
+describe('filter schemas', () => {
+	describe('CommonFilters', () => {
+		it('coerces page and limit from query-string text', () => {
+			expect(CommonFilters.parse({ page: '2', limit: '10' })).toEqual({
+				page: 2,
+				limit: 10
+			});
+		});
+
+		it.each(['0', '-1', '1.5', 'abc'])('rejects page=%s', (page) => {
+			expect(CommonFilters.safeParse({ page }).success).toBe(false);
+		});
+
+		it('drops unknown query parameters', () => {
+			expect(CommonFilters.parse({ page: '1', debug: 'true' })).toEqual({
+				page: 1
+			});
+		});
+	});
+
+	describe('DateFilters', () => {
+		it('accepts a date or an ISO date-time', () => {
+			expect(
+				DateFilters.parse({ from: '2026-01-01', to: '2026-12-31T23:59:59Z' })
+			).toEqual({ from: '2026-01-01', to: '2026-12-31T23:59:59Z' });
+		});
+
+		it('rejects anything else', () => {
+			expect(DateFilters.safeParse({ from: 'yesterday' }).success).toBe(false);
+		});
+	});
+});

package/templates/nest-api/files/src/common/__tests__/throttler-storage.service.spec.ts

@@ -0,0 +1,80 @@
+import { CacheService, RedisThrottlerStorage } from 'common/services';
+
+type IncrementResult = [number, number, number, number];
+
+/**
+ * The Lua script itself is exercised against real Redis by `test/rate-limit.spec.ts`.
+ * Here we pin the contract around it: argument marshalling and the ms → s
+ * conversion that `ThrottlerGuard` relies on for `Retry-After`.
+ */
+const makeCache = (result: IncrementResult) => {
+	const throttlerIncrement = vi.fn().mockResolvedValue(result);
+	const defineCommand = vi.fn();
+	const cache = {
+		db: { defineCommand, throttlerIncrement }
+	} as unknown as CacheService;
+
+	return { cache, throttlerIncrement, defineCommand };
+};
+
+describe('RedisThrottlerStorage', () => {
+	it('registers the Lua command once on construction', () => {
+		const { cache, defineCommand } = makeCache([1, 60_000, 0, 0]);
+		new RedisThrottlerStorage(cache);
+
+		expect(defineCommand).toHaveBeenCalledWith(
+			'throttlerIncrement',
+			expect.objectContaining({ numberOfKeys: 2 })
+		);
+	});
+
+	it('passes the hits and block keys, namespaced by throttler name', async () => {
+		const { cache, throttlerIncrement } = makeCache([1, 60_000, 0, 0]);
+		const storage = new RedisThrottlerStorage(cache);
+
+		await storage.increment('abc123', 60_000, 30, 60_000, 'default');
+
+		expect(throttlerIncrement).toHaveBeenCalledWith(
+			'throttle:default:abc123',
+			'throttle:default:abc123:block',
+			60_000,
+			30,
+			60_000
+		);
+	});
+
+	it('converts millisecond TTLs to the seconds the guard expects', async () => {
+		const { cache } = makeCache([1, 59_400, 0, 0]);
+		const storage = new RedisThrottlerStorage(cache);
+
+		const record = await storage.increment('k', 60_000, 30, 60_000, 'default');
+
+		expect(record).toEqual({
+			totalHits: 1,
+			timeToExpire: 60, // ceil(59_400 / 1000)
+			isBlocked: false,
+			timeToBlockExpire: 0
+		});
+	});
+
+	it('reports a block with its remaining time in seconds', async () => {
+		const { cache } = makeCache([31, 42_000, 1, 30_500]);
+		const storage = new RedisThrottlerStorage(cache);
+
+		const record = await storage.increment('k', 60_000, 30, 60_000, 'default');
+
+		expect(record.isBlocked).toBe(true);
+		expect(record.totalHits).toBe(31);
+		expect(record.timeToBlockExpire).toBe(31); // ceil(30_500 / 1000)
+	});
+
+	it('clamps negative TTLs (expired or missing key) to zero', async () => {
+		const { cache } = makeCache([1, -2, 0, -2]);
+		const storage = new RedisThrottlerStorage(cache);
+
+		const record = await storage.increment('k', 60_000, 30, 60_000, 'default');
+
+		expect(record.timeToExpire).toBe(0);
+		expect(record.timeToBlockExpire).toBe(0);
+	});
+});

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

@@ -0,0 +1,72 @@
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TerminusModule } from '@nestjs/terminus'; // @feature observability
+import { LoggerModule } from './modules';
+import { MetricsModule } from './modules'; // @feature observability
+// The queue module itself is generic; here it is only needed to register the
+// `mail` queue, so it rides on the mail feature.
+import { QueueModule } from './modules'; // @feature mail
+import {
+	GeneratorService,
+	CustomConfigService,
+	PrismaService,
+	CustomAuthService
+} from './services';
+import { CacheService } from './services'; // @feature cache
+import { MailService } from './services'; // @feature mail
+import { RedisThrottlerStorage } from './services'; // @feature rate-limit
+import { FeatureFlagService } from './services'; // @feature feature-flags
+import { HealthController } from './controllers'; // @feature observability
+import { MailProcessor } from './processors'; // @feature mail
+import { FeatureFlagGuard } from './guards'; // @feature feature-flags
+import { PrismaHealthIndicator } from './misc'; // @feature observability
+import Config from './services/config.service';
+
+/**
+ * Global infrastructure module. Everything listed in `exports` is injectable
+ * anywhere without importing this module — extend that array when you add a
+ * shared provider, or the rest of the app will not see it.
+ */
+@Global()
+@Module({
+	imports: [
+		ConfigModule.forRoot({
+			load: [Config.getVariables],
+			validationSchema: Config.schema
+		}),
+		LoggerModule,
+		// @feature:start observability
+		TerminusModule,
+		MetricsModule,
+		// @feature:end
+		QueueModule.register('mail') // @feature mail
+	],
+	controllers: [
+		HealthController // @feature observability
+	],
+	providers: [
+		ConfigService,
+		CustomConfigService,
+		GeneratorService,
+		PrismaService,
+		CustomAuthService,
+		CacheService, // @feature cache
+		MailService, // @feature mail
+		MailProcessor, // @feature mail
+		RedisThrottlerStorage, // @feature rate-limit
+		FeatureFlagService, // @feature feature-flags
+		FeatureFlagGuard, // @feature feature-flags
+		PrismaHealthIndicator // @feature observability
+	],
+	exports: [
+		CustomConfigService,
+		GeneratorService,
+		PrismaService,
+		CustomAuthService,
+		CacheService, // @feature cache
+		MailService, // @feature mail
+		RedisThrottlerStorage, // @feature rate-limit
+		FeatureFlagService // @feature feature-flags
+	]
+})
+export class CommonModule {}

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

@@ -0,0 +1,2 @@
+export * from './options';
+export * from './pino';

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

@@ -0,0 +1,52 @@
+import 'dotenv/config';
+import { DocumentBuilder } from '@nestjs/swagger'; // @feature openapi
+import { OriginBuilder } from '../misc';
+
+// Read directly from `process.env`, not CustomConfigService: these constants are
+// evaluated at module load, before Nest's DI container exists.
+const { env: E } = process;
+
+const port = E.PORT!;
+const host = E.SERVER_HOST!;
+const appHost = E.APP_HOST!;
+const frontendHost = E.FRONTEND_HOST!;
+
+const env = E.APP_ENV!;
+const IS_DEV = env === 'development';
+
+// Extra origins are a development convenience only — production is pinned to
+// the configured frontend host.
+const CORS_ORIGINS = !IS_DEV
+	? [frontendHost]
+	: [frontendHost, ...OriginBuilder.build(E.MISC_CORS_ORIGINS)];
+
+// @feature:start openapi
+const createDocumentBuilder = () => {
+	const builder = new DocumentBuilder()
+		.setTitle('Acme Corp API')
+		.setDescription('API for the Acme Corp application')
+		.setVersion('1.0')
+		.addTag('App')
+		.addTag('Users', 'User management and authentication')
+		.addTag('Current User', 'Current authenticated user information')
+		.addBearerAuth();
+
+	builder.addServer(host);
+	if (IS_DEV) {
+		builder
+			.addServer(`http://localhost:${port}`, 'Local Development')
+			.addServer(`http://${appHost}:${port}`, 'Dynamic Development');
+	}
+	return builder.build();
+};
+
+export const SWAGGER_OPTIONS = createDocumentBuilder();
+// @feature:end
+
+export const CORS_OPTIONS = {
+	origin: CORS_ORIGINS,
+	credentials: true,
+	methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
+	preflightContinue: false,
+	optionsSuccessStatus: 204
+};

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

@@ -0,0 +1,24 @@
+export const PINO_CONSOLE_TARGET = {
+	target: 'pino-pretty',
+	options: {
+		ignore: 'pid,hostname',
+		translateTime: 'SYS:dd-mm-yyyy HH:MM:ss',
+		singleLine: true,
+		colorize: true
+	}
+};
+
+export const PINO_FILE_TARGET = {
+	target: 'pino/file',
+	options: {
+		destination: 'logs/app.log',
+		mkdir: true
+	}
+};
+
+export const PINO_CONSOLE_TARGET_PROD = {
+	target: 'pino/file',
+	options: {
+		destination: 1
+	}
+};

package/templates/nest-api/files/src/common/controllers/health.controller.ts

@@ -0,0 +1,54 @@
+import { Controller, Get, VERSION_NEUTRAL } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
+import {
+	HealthCheckService,
+	HttpHealthIndicator,
+	HealthCheck,
+	DiskHealthIndicator,
+	MemoryHealthIndicator
+} from '@nestjs/terminus';
+import { SkipThrottle } from '@nestjs/throttler'; // @feature rate-limit
+import { AllowAnonymous } from '@thallesp/nestjs-better-auth';
+import { Op } from 'common/decorators';
+import { CustomConfigService } from '../services';
+import { PrismaHealthIndicator } from '../misc';
+
+const MB = 1024 * 1024;
+
+@ApiTags('App')
+@Controller({ path: 'health', version: VERSION_NEUTRAL })
+// @feature:start rate-limit
+// Probed on a fixed interval by orchestrators; throttling it would take the
+// service out of rotation under exactly the load it exists to report on.
+@SkipThrottle()
+// @feature:end
+export class HealthController {
+	constructor(
+		private health: HealthCheckService,
+		private http: HttpHealthIndicator,
+		private config: CustomConfigService,
+		private prisma: PrismaHealthIndicator,
+		private disk: DiskHealthIndicator,
+		private memory: MemoryHealthIndicator
+	) {}
+
+	@Get()
+	@ApiExcludeEndpoint()
+	@Op('health', '/health', 'Check the health of the server')
+	@HealthCheck()
+	@AllowAnonymous()
+	async check() {
+		const { heapMaxMb, rssMaxMb, diskThreshold, diskPath } = this.config.health;
+		return this.health.check([
+			() => this.http.pingCheck('http', this.config.app.host),
+			() => this.prisma.isHealthy('database'),
+			() => this.memory.checkHeap('memory_heap', heapMaxMb * MB),
+			() => this.memory.checkRSS('memory_rss', rssMaxMb * MB),
+			() =>
+				this.disk.checkStorage('disk_storage', {
+					thresholdPercent: diskThreshold,
+					path: diskPath
+				})
+		]);
+	}
+}

package/templates/nest-api/files/src/common/controllers/index.ts

@@ -0,0 +1,2 @@
+export * from './metrics.controller'; // @feature observability
+export * from './health.controller'; // @feature observability

package/templates/nest-api/files/src/common/controllers/metrics.controller.ts

@@ -0,0 +1,21 @@
+import { Controller, Get, Res } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
+import { SkipThrottle } from '@nestjs/throttler'; // @feature rate-limit
+import { AllowAnonymous } from '@thallesp/nestjs-better-auth';
+import { PrometheusController } from '@willsoto/nestjs-prometheus';
+import type { Response } from 'express';
+
+@ApiTags('App')
+@Controller()
+// @feature:start rate-limit
+// Scraped on a fixed interval by Prometheus; already gated by basic auth.
+@SkipThrottle()
+// @feature:end
+export class MetricsController extends PrometheusController {
+	@Get()
+	@ApiExcludeEndpoint()
+	@AllowAnonymous()
+	async index(@Res({ passthrough: true }) response: Response): Promise<string> {
+		return super.index(response);
+	}
+}

package/templates/nest-api/files/src/common/decorators/index.ts

@@ -0,0 +1,2 @@
+export * from './multi-part.decorator';
+export * from './misc.decorator';

package/templates/nest-api/files/src/common/decorators/misc.decorator.ts

@@ -0,0 +1,49 @@
+import { applyDecorators, SerializeOptions } from '@nestjs/common';
+import {
+	ApiOkResponse,
+	ApiParam,
+	ApiOperation,
+	ApiOperationOptions,
+	ApiResponseOptions
+} from '@nestjs/swagger';
+import type { z } from 'zod';
+
+/**
+ * Declare what a handler returns: the schema is published as the OpenAPI
+ * response and, through the global StandardSchemaSerializerInterceptor, is
+ * what the response is serialized with — fields it does not declare are
+ * dropped, and a return value that does not match fails loudly.
+ */
+export function Returns(
+	schema: z.ZodType,
+	options: Omit<ApiResponseOptions, 'type' | 'schema' | 'standardSchema'> = {}
+) {
+	return applyDecorators(
+		ApiOkResponse({ ...options, standardSchema: schema }),
+		SerializeOptions({ schema })
+	);
+}
+
+export function IdParam(name = 'id') {
+	return applyDecorators(ApiParam({ name, type: String }));
+}
+
+type OperationOptions = Omit<
+	ApiOperationOptions,
+	'summary' | 'description' | 'operationId'
+>;
+export function Op(
+	operationId: string,
+	summary: string,
+	description: string | undefined = undefined,
+	options: OperationOptions = {}
+) {
+	return applyDecorators(
+		ApiOperation({
+			summary,
+			operationId,
+			description,
+			...options
+		})
+	);
+}

package/templates/nest-api/files/src/common/decorators/multi-part.decorator.ts

@@ -0,0 +1,6 @@
+import { applyDecorators } from '@nestjs/common';
+import { ApiConsumes } from '@nestjs/swagger';
+
+export function MultipartFormData() {
+	return applyDecorators(ApiConsumes('multipart/form-data'));
+}

package/templates/nest-api/files/src/common/dto/filters.dto.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { search } from '../schemas';
+
+// Query strings arrive as text, so numbers are coerced before they are checked.
+const pageNumber = () => z.coerce.number().int().min(1).optional();
+
+export const CommonFilters = z.object({
+	search: search(),
+	limit: pageNumber(),
+	page: pageNumber()
+});
+export type CommonFilters = z.output<typeof CommonFilters>;
+
+// ISO 8601: a date, or a date-time with an offset.
+const isoDateOrDateTime = () =>
+	z
+		.union([z.iso.date(), z.iso.datetime({ offset: true })])
+		.optional()
+		.meta({ example: '2026-01-01T00:00:00.000Z' });
+
+export const DateFilters = z.object({
+	from: isoDateOrDateTime(),
+	to: isoDateOrDateTime()
+});
+export type DateFilters = z.output<typeof DateFilters>;

package/templates/nest-api/files/src/common/dto/index.ts

@@ -0,0 +1 @@
+export * from './filters.dto';

package/templates/nest-api/files/src/common/entity/index.ts

@@ -0,0 +1,2 @@
+export * from './ok.entity';
+export * from './pagination.entity';

package/templates/nest-api/files/src/common/entity/ok.entity.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+
+export const OKEntity = z
+	.object({
+		status: z.number().meta({ example: 200 }),
+		message: z.string().meta({ example: 'ok' })
+	})
+	.meta({ id: 'OKEntity' });
+export type OKEntity = z.input<typeof OKEntity>;
+
+export const ok = (): OKEntity => ({ status: 200, message: 'ok' });