@aurostack/stacks 0.1.0

package/templates/nest-api/template.json

@@ -0,0 +1,452 @@
+{
+	"name": "nest-api",
+	"version": "0.1.0",
+	"title": "NestJS API",
+	"description": "NestJS 12 + Prisma (Postgres) + Redis + BullMQ + better-auth + Vitest, with Docker Compose for local Postgres/Redis and a Scalar API reference.",
+	"defaults": {
+		"port": 5000
+	},
+	"replacements": [
+		{
+			"from": "@starter/backend",
+			"to": "@{{scope}}/api"
+		},
+		{
+			"from": "Acme Corp",
+			"to": "{{Name}}"
+		},
+		{
+			"from": "AcmeCorp",
+			"to": "{{pascal}}"
+		},
+		{
+			"from": "acme-corp",
+			"to": "{{name}}"
+		},
+		{
+			"from": "acmecorp",
+			"to": "{{name}}"
+		},
+		{
+			"from": "acme",
+			"to": "{{name}}"
+		},
+		{
+			"from": "\\bnum\\(\\)\\.default\\(5000\\)",
+			"to": "num().default({{port}})",
+			"regex": true
+		},
+		{
+			"from": "Number\\(env\\.PORT\\) \\|\\| 5000",
+			"to": "Number(env.PORT) || {{port}}",
+			"regex": true
+		},
+		{
+			"from": "^PORT='5000'$",
+			"to": "PORT='{{port}}'",
+			"regex": true,
+			"flags": "gm"
+		},
+		{
+			"from": "^EXPOSE 5000$",
+			"to": "EXPOSE {{port}}",
+			"regex": true,
+			"flags": "gm"
+		}
+	],
+	"features": {
+		"prisma": {
+			"title": "Prisma ORM + Postgres",
+			"description": "PrismaService, multi-file schema, the .bin/db.ts env-aware wrapper, and the Prisma exception filters.",
+			"core": true
+		},
+		"config": {
+			"title": "Zod-validated config service",
+			"description": "CustomConfigService wrapping @nestjs/config; app code never reads process.env directly.",
+			"core": true
+		},
+		"auth": {
+			"title": "better-auth (email/password, OAuth, roles)",
+			"description": "Global AuthGuard so every route is authenticated by default, @AllowAnonymous to opt out, access-control statements and roles in lib/access.ts.",
+			"core": true,
+			"requires": [
+				"prisma"
+			]
+		},
+		"cache": {
+			"title": "Redis cache",
+			"description": "CacheService on ioredis, plus the key-namespacing helpers. Required by the queue, throttler and realtime layers.",
+			"default": true,
+			"files": [
+				"src/common/services/cache.service.ts",
+				"src/common/utils/redis.keys.ts",
+				"src/common/__tests__/cache.service.spec.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"ioredis"
+				]
+			}
+		},
+		"queue": {
+			"title": "BullMQ background jobs",
+			"description": "QueueModule.register(), the Bull Board dashboard at /dashboard behind basic auth.",
+			"default": true,
+			"requires": [
+				"cache"
+			],
+			"files": [
+				"src/common/modules/queue.module.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@nestjs/bullmq",
+					"bullmq",
+					"@bull-board/api",
+					"@bull-board/express",
+					"@bull-board/nestjs"
+				]
+			}
+		},
+		"mail": {
+			"title": "Transactional email",
+			"description": "MailService enqueuing onto the `mail` queue, a MailProcessor consumer, and React Email templates with a dev preview server.",
+			"default": true,
+			"requires": [
+				"queue"
+			],
+			"files": [
+				"src/common/services/mail.service.ts",
+				"src/common/processors/**",
+				"src/common/types/email.ts",
+				"emails/**",
+				"__mocks__/**",
+				"src/common/__tests__/mail.service.spec.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@nestjs-modules/mailer",
+					"nodemailer",
+					"react",
+					"react-email",
+					"@react-email/components",
+					"@react-email/render"
+				],
+				"devDependencies": [
+					"@types/nodemailer",
+					"@types/react"
+				],
+				"scripts": [
+					"email:dev"
+				]
+			}
+		},
+		"rate-limit": {
+			"title": "Two-layer rate limiting",
+			"description": "ThrottlerGuard on a Redis Lua storage for app routes, plus better-auth's own limiter for /auth/* with per-endpoint rules.",
+			"default": true,
+			"requires": [
+				"cache"
+			],
+			"files": [
+				"src/common/services/throttler-storage.service.ts",
+				"src/common/services/auth-rate-limit.storage.ts",
+				"src/lib/rate-limit.ts",
+				"src/common/utils/ip.ts",
+				"src/common/__tests__/throttler-storage.service.spec.ts",
+				"test/rate-limit.spec.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@nestjs/throttler"
+				]
+			}
+		},
+		"openapi": {
+			"title": "OpenAPI + Scalar reference",
+			"description": "Swagger document at /openapi and a Scalar UI at /docs (auth + main API), both behind basic auth. Core rather than optional: @ApiTags/@ApiProperty decorators are pervasive in the controller and entity conventions, so removing @nestjs/swagger would mean annotating hundreds of lines.",
+			"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.",
+			"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"
+			],
+			"packageJson": {
+				"dependencies": [
+					"prom-client",
+					"@willsoto/nestjs-prometheus",
+					"@nestjs/terminus"
+				]
+			}
+		},
+		"users": {
+			"title": "Users module",
+			"description": "Admin-style user listing/lookup gated by permissions, plus the authenticated user's own /me resource and avatar upload.",
+			"default": true,
+			"requires": [
+				"auth"
+			],
+			"files": [
+				"src/users/**",
+				"test/users.spec.ts",
+				"test/current-user.spec.ts"
+			]
+		},
+		"media": {
+			"title": "File uploads (S3)",
+			"description": "MediaService and S3Service for public and private uploads, with multipart decorators.",
+			"default": true,
+			"requires": [
+				"auth"
+			],
+			"files": [
+				"src/media/**",
+				"src/users/dto/avatar.dto.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@aws-sdk/client-s3"
+				],
+				"devDependencies": [
+					"@types/multer"
+				]
+			}
+		},
+		"scheduler": {
+			"title": "Cron / interval scheduling",
+			"description": "@nestjs/schedule wired at the root so modules can declare @Cron and @Interval jobs.",
+			"default": true,
+			"packageJson": {
+				"dependencies": [
+					"@nestjs/schedule"
+				]
+			}
+		},
+		"http-client": {
+			"title": "Outbound HTTP client",
+			"description": "@nestjs/axios registered with a default timeout, for calling third-party APIs.",
+			"default": true,
+			"packageJson": {
+				"dependencies": [
+					"@nestjs/axios",
+					"axios"
+				]
+			}
+		},
+		"realtime": {
+			"title": "Socket.IO realtime layer",
+			"description": "An authenticated gateway, Redis-backed presence, a Redis Socket.IO adapter for horizontal scale, and WS auth/permission guards. Opt-in.",
+			"requires": [
+				"cache",
+				"auth"
+			],
+			"files": [
+				"src/realtime/**"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@nestjs/websockets",
+					"@nestjs/platform-socket.io",
+					"socket.io",
+					"@socket.io/redis-adapter"
+				]
+			}
+		},
+		"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.",
+			"requires": [
+				"auth"
+			],
+			"files": [
+				"src/notifications/**",
+				"prisma/schema/notification.prisma",
+				"test/notifications.spec.ts"
+			]
+		},
+		"feature-flags": {
+			"title": "GrowthBook feature flags",
+			"description": "A session-aware FeatureFlagGuard and FeatureFlagService for gating routes on flags.",
+			"requires": [
+				"cache",
+				"auth"
+			],
+			"files": [
+				"src/common/services/feature-flag.service.ts",
+				"src/common/guards/feature-flag.guard.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@growthbook/growthbook"
+				]
+			}
+		},
+		"graphql": {
+			"title": "GraphQL endpoint",
+			"description": "Code-first GraphQL via Apollo, registered alongside the REST controllers. Resolvers in any feature module are picked up automatically.",
+			"files": [
+				"src/app.resolver.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@nestjs/graphql",
+					"@nestjs/apollo",
+					"@apollo/server",
+					"@as-integrations/express5",
+					"graphql"
+				]
+			}
+		},
+		"testing": {
+			"title": "Vitest unit + e2e suites",
+			"description": "Two Vitest projects, an AppFactory that boots the real app against real Postgres and Redis, and a test Docker stack.",
+			"default": true,
+			"requires": [
+				"docker"
+			],
+			"files": [
+				"test/**",
+				"src/**/__tests__/**",
+				"vitest.config.ts",
+				"compose.test.yml",
+				".env.test.example"
+			],
+			"packageJson": {
+				"devDependencies": [
+					"vitest",
+					"@vitest/coverage-v8",
+					"@vitest/ui",
+					"@suites/di.nestjs",
+					"@suites/doubles.vitest",
+					"@suites/unit",
+					"@golevelup/ts-vitest",
+					"@nestjs/testing",
+					"supertest",
+					"@types/supertest",
+					"fishery",
+					"unplugin-swc",
+					"dotenv-cli"
+				],
+				"scripts": [
+					"test",
+					"test:watch",
+					"test:ui",
+					"test:e2e",
+					"test:e2e:watch",
+					"test:e2e:ui",
+					"test:cov",
+					"test:all",
+					"test:all:ui",
+					"test:db:generate",
+					"test:db:push",
+					"test:db:seed",
+					"test:dc:up",
+					"test:dc:wait",
+					"test:dc:down",
+					"test:dc:recreate",
+					"test:dc:reinstall"
+				]
+			}
+		},
+		"docker": {
+			"title": "Docker Compose + image",
+			"description": "compose.yml running Postgres and Redis for local dev, a production Dockerfile, and the .bin/dc.ts stack wrapper.",
+			"default": true,
+			"files": [
+				"Dockerfile",
+				".dockerignore",
+				"compose.yml",
+				".bin/dc.ts"
+			],
+			"packageJson": {
+				"scripts": [
+					"dc:up",
+					"dc:down",
+					"dc:wait",
+					"dc:recreate",
+					"dc:reinstall",
+					"down",
+					"reinstall"
+				]
+			}
+		},
+		"ci": {
+			"title": "Forgejo Actions CI",
+			"description": "A workflow that spins up the test stack and runs both Vitest projects on pull requests.",
+			"default": true,
+			"files": [
+				".forgejo/**"
+			]
+		},
+		"secrets": {
+			"title": "Infisical secret sync",
+			"description": "`yarn secrets -e <env>` pulls the matching .env file instead of passing secrets around by hand.",
+			"default": true,
+			"files": [
+				".bin/secrets.ts"
+			],
+			"packageJson": {
+				"scripts": [
+					"secrets"
+				]
+			}
+		}
+	},
+	"hooks": [
+		{
+			"title": "seed .env from .env.example",
+			"run": "cp -n .env.example .env || true",
+			"optional": true
+		},
+		{
+			"title": "seed .env.test from .env.test.example",
+			"run": "cp -n .env.test.example .env.test || true",
+			"when": "testing",
+			"optional": true
+		},
+		{
+			"title": "yarn install",
+			"run": "yarn install",
+			"optional": true
+		},
+		{
+			"title": "format (the feature strip leaves valid but unformatted code)",
+			"run": "yarn format",
+			"optional": true
+		},
+		{
+			"title": "prisma generate",
+			"run": "yarn db:generate",
+			"optional": true
+		},
+		{
+			"title": "git init",
+			"run": "git init -q && git add -A && git commit -qm 'chore: scaffold {{name}} from the nest-api template'",
+			"optional": true
+		}
+	],
+	"nextSteps": [
+		"Edit .env — DATABASE_URL, REDIS_*, BETTER_AUTH_SECRET and SMTP_* have placeholder values.",
+		"yarn dc:up          # start Postgres + Redis",
+		"yarn db:migrate     # create the initial migration",
+		"yarn start          # http://localhost:{{port}}/docs"
+	],
+	"aliasRoots": {
+		"@db/": null,
+		"@test/": "test/",
+		"@emails/": "emails/",
+		"@seeders/": "seeders/"
+	},
+	"generatedPaths": [
+		"prisma/generated/**"
+	]
+}

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

@@ -0,0 +1,123 @@
+import { Argv, Env } from './helpers.js';
+
+interface ArgsResponse {
+	cmd: string;
+	env: Env;
+	name?: string;
+}
+
+class CommandBuilder {
+	private command: string[];
+
+	private constructor(private env: Env = 'dev') {
+		if (env === 'prod') {
+			this.command = ['dotenv -e .env.production --', 'prisma'];
+		} else if (env === 'test') {
+			this.command = ['dotenv -e .env.test --', 'prisma'];
+		} else {
+			this.command = ['prisma'];
+		}
+	}
+
+	static init(env: Env) {
+		return new CommandBuilder(env);
+	}
+
+	generate() {
+		this.command.push('generate');
+		return this;
+	}
+
+	push() {
+		// push targets test/prod (reseeded), so accept column drops non-interactively.
+		this.command.push('db push --accept-data-loss');
+		return this;
+	}
+
+	reset() {
+		this.command.push('migrate reset --force');
+		return this;
+	}
+
+	studio() {
+		this.command.push('studio --browser none --port 5025');
+		return this;
+	}
+
+	seed() {
+		this.command.push('db seed');
+		return this;
+	}
+
+	build() {
+		return this.command.join(' ');
+	}
+}
+
+class Database extends Argv {
+	private async getArgs(): Promise<ArgsResponse> {
+		const argv = await this.args
+			.option('command', {
+				type: 'string',
+				description: 'Specify the command to run',
+				choices: ['generate', 'push', 'seed', 'reset', 'studio'],
+				default: 'generate',
+				alias: 'c'
+			})
+			.option('name', {
+				type: 'string',
+				description:
+					'Use a specific name for the migration (only for migrate or migrate:create command)',
+				alias: 'n'
+			}).argv;
+		return {
+			cmd: argv.command,
+			env: this.getEnv(argv.env),
+			name: argv.name
+		};
+	}
+
+	private async getCommand() {
+		const { env, cmd, name } = await this.getArgs();
+		const command = CommandBuilder.init(env);
+		if (cmd === 'push') {
+			return command.push().build();
+		}
+
+		if (cmd === 'seed') {
+			return command.seed().build();
+		}
+
+		if (cmd === 'reset') {
+			if (['test', 'prod'].includes(env)) {
+				this.err(
+					'Reset command is not allowed in test or production environment'
+				);
+			}
+			return command.reset().build();
+		}
+
+		if (cmd === 'studio') {
+			if (env === 'prod') {
+				this.err('Studio command is not allowed in production environment');
+			}
+			return command.studio().build();
+		}
+
+		return command.generate().build();
+	}
+
+	async run() {
+		this.clear();
+		const command = await this.getCommand();
+		this.exec(command);
+	}
+
+	static init() {
+		return new Database();
+	}
+}
+
+Database.init()
+	.run()
+	.catch((e) => console.error(e.message));

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

@@ -0,0 +1,49 @@
+import shell from 'shelljs';
+import yargs, { Argv as IArgv } from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+export type Env = 'dev' | 'prod' | 'test';
+
+export abstract class Argv {
+	protected args: IArgv<any>;
+
+	constructor() {
+		this.args = yargs(hideBin(process.argv))
+			.help('help')
+			.alias('help', 'h')
+			.option('env', {
+				type: 'string',
+				description: 'Specify the environment to use',
+				choices: [
+					'dev',
+					'development',
+					'prod',
+					'production',
+					'test',
+					'testing'
+				],
+				default: 'dev',
+				alias: 'e'
+			});
+	}
+
+	getEnv(env: string): Env {
+		return ['test', 'testing'].includes(env)
+			? 'test'
+			: ['prod', 'production'].includes(env)
+				? 'prod'
+				: 'dev';
+	}
+
+	clear() {
+		console.clear();
+	}
+
+	err(message: string) {
+		throw new Error(`❌ ${message}`);
+	}
+
+	exec(command: string) {
+		shell.exec(command);
+	}
+}

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

@@ -0,0 +1,68 @@
+import shell from 'shelljs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+const getArg = async () => {
+	const argv = await yargs(hideBin(process.argv))
+		.option('env', {
+			alias: 'e',
+			description: 'The environment [dev, test, prod, etc.]',
+			type: 'string',
+			choices: [
+				'dev',
+				'development',
+				'test',
+				'testing',
+				'staging',
+				'prod',
+				'production'
+			],
+			default: 'development'
+		})
+		.help()
+		.alias('help', 'h').argv;
+
+	return ['dev', 'development'].includes(argv.env)
+		? 'dev'
+		: ['test', 'testing'].includes(argv.env)
+			? 'test'
+			: ['prod', 'production'].includes(argv.env)
+				? 'prod'
+				: 'staging';
+};
+
+const getEnvFile = (env: string) => {
+	const envMap: Record<string, string> = {
+		dev: '.env',
+		test: '.env.test',
+		staging: '.env.staging',
+		prod: '.env.production'
+	};
+
+	return envMap[env];
+};
+
+// The project ID identifies one organisation's vault, so it is read from the
+// environment rather than baked in — a hardcoded value would follow every copy
+// of this scaffold to projects it has nothing to do with.
+const PROJECT_ID = process.env.INFISICAL_PROJECT_ID;
+const SECRET_PATH = process.env.INFISICAL_PATH ?? '/';
+
+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
+	)}`;
+};
+
+const log = (env: string) => console.log(`Fetching secrets for '${env}'...`);
+
+(async () => {
+	const env = await getArg();
+	const command = getCmd(env);
+	log(env);
+	shell.exec(command);
+	process.exit(0);
+})().catch(console.error);

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

@@ -0,0 +1,5 @@
+node_modules
+dist
+tmp
+.env
+*.md