@aurostack/stacks 0.1.0

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

@@ -0,0 +1,123 @@
+import { Argv, Env } from './helpers';
+
+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/nest-api/files/.bin/dc.ts

@@ -0,0 +1,74 @@
+import { Argv } from './helpers';
+
+/**
+ * Compose services that `up` / `recreate` bring online. Redis is only a service
+ * when the cache feature is kept, so the list is assembled here rather than
+ * being spelled out in four command strings.
+ */
+const SERVICES = [
+	'database',
+	'redis' // @feature cache
+].join(' ');
+
+const TEST = 'docker compose -f compose.test.yml -p test';
+
+class DockerCompose extends Argv {
+	private async getArgs() {
+		const argv = await this.args.option('command', {
+			type: 'string',
+			description: 'Specify the docker-compose command to run',
+			choices: ['up', 'wait', 'down', 'recreate'],
+			demandOption: true,
+			alias: 'c'
+		}).argv;
+		return {
+			cmd: argv.command,
+			env: this.getEnv(argv.env)
+		};
+	}
+
+	private async getCommand(): Promise<string | undefined> {
+		const { cmd, env } = await this.getArgs();
+		if (env === 'dev') {
+			if (cmd === 'up') return `docker compose up -d ${SERVICES}`;
+			if (cmd === 'wait') return 'docker compose run wait';
+			if (cmd === 'down') return 'docker compose down';
+			if (cmd === 'recreate')
+				return `docker compose down && docker compose up -d ${SERVICES} && docker compose run wait`;
+
+			return undefined;
+		}
+
+		if (env === 'test') {
+			if (cmd === 'up') return `${TEST} up -d ${SERVICES}`;
+			if (cmd === 'wait') return `${TEST} run wait`;
+			if (cmd === 'down') return `${TEST} down`;
+			if (cmd === 'recreate')
+				return `${TEST} down && ${TEST} up -d ${SERVICES} && ${TEST} run wait`;
+
+			return undefined;
+		}
+
+		return undefined;
+	}
+
+	async run() {
+		this.clear();
+		const command = await this.getCommand();
+		if (!command) {
+			this.err(
+				`The command is ONLY implemented for the development and test environments.`
+			);
+			return;
+		}
+		this.exec(command);
+	}
+
+	static init() {
+		return new DockerCompose();
+	}
+}
+
+DockerCompose.init()
+	.run()
+	.catch((e) => console.error(e.message));

package/templates/nest-api/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/nest-api/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/nest-api/files/.bin/start.ts

@@ -0,0 +1,47 @@
+import { Argv } from './helpers';
+
+class Start extends Argv {
+	private async getArgs() {
+		const argv = await this.args
+			.option('watch', {
+				type: 'boolean',
+				description:
+					'Start the server in development mode with hot-reload (watch mode)',
+				default: true,
+				alias: 'w'
+			})
+			.option('debug', {
+				type: 'boolean',
+				description: 'Start the server in debug mode',
+				default: false,
+				alias: 'd'
+			}).argv;
+		return argv;
+	}
+
+	private async getCommand() {
+		const args = await this.getArgs();
+		const command = ['nest', 'start'];
+		if (args.watch) {
+			command.push('--watch');
+		}
+		if (args.debug) {
+			command.push('--debug');
+		}
+		return command.join(' ');
+	}
+
+	async run() {
+		this.clear();
+		const command = await this.getCommand();
+		this.exec(command);
+	}
+
+	static init() {
+		return new Start();
+	}
+}
+
+Start.init()
+	.run()
+	.catch((e) => console.error(e.message));

package/templates/nest-api/files/.dockerignore

@@ -0,0 +1,7 @@
+dist/
+node_modules/
+package-lock.json
+.npmrc.example
+.env
+.env.example
+.env.test

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

@@ -0,0 +1,91 @@
+# Copy to .env and fill in. Every variable here is validated at boot by
+# src/common/services/config.service.ts — the process refuses to start if a
+# required one is missing, rather than failing later inside a request.
+
+APP_ENV='development'
+APP_NAME='Acme Corp'
+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.
+MISC_CORS_ORIGINS=''
+
+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'
+BETTER_AUTH_COOKIE_PREFIX='acme'
+
+# Seeded by `yarn db:seed`.
+SUPERUSER_EMAIL='admin@example.com'
+SUPERUSER_PASSWORD='Secret@1'
+
+OAUTH_GOOGLE_CLIENT_ID=''
+OAUTH_GOOGLE_CLIENT_SECRET=''
+
+LOG_LEVEL='debug'
+
+# @feature:start observability
+# Limits past which /health reports down. Size them to the container's real
+# limits: an orchestrator restarts instances that fail this check.
+HEALTH_HEAP_MAX_MB='300'
+HEALTH_RSS_MAX_MB='300'
+# Fraction (0–1) of HEALTH_DISK_PATH's volume that may be used.
+HEALTH_DISK_THRESHOLD='0.8'
+HEALTH_DISK_PATH='/'
+# @feature:end
+
+# @feature:start openapi, queue, observability
+# Guards /docs, /openapi-json, /dashboard and /metrics.
+BASIC_AUTH_USER='admin'
+BASIC_AUTH_PASS='Secret@1'
+# @feature:end
+
+# @feature:start cache
+REDIS_HOST='localhost'
+REDIS_PORT='6379'
+REDIS_USER=''
+REDIS_PASSWORD=''
+# @feature:end
+
+# @feature:start mail
+SMTP_HOST='smtp.example.com'
+SMTP_PORT='465'
+SMTP_SECURE='true'
+SMTP_USER=''
+SMTP_PASSWORD=''
+SMTP_FROM='Acme Corp <no-reply@example.com>'
+SMTP_SUPPORT_EMAIL='support@example.com'
+# @feature:end
+
+# @feature:start media
+S3_REGION='us-east-1'
+# Leave empty for AWS; set it for MinIO or another S3-compatible host.
+S3_ENDPOINT=''
+S3_BUCKET_NAME='acme'
+S3_ACCESS_KEY_ID=''
+S3_SECRET_ACCESS_KEY=''
+# @feature:end
+
+# @feature:start rate-limit
+RATE_LIMIT_ENABLED='true'
+# Throttler TTLs are in milliseconds.
+RATE_LIMIT_TTL='60000'
+RATE_LIMIT_MAX='120'
+# better-auth's own window is in seconds.
+RATE_LIMIT_AUTH_WINDOW='10'
+RATE_LIMIT_AUTH_MAX='100'
+# Load-bearing behind a proxy: if no IP can be resolved, better-auth skips rate
+# limiting entirely and only warns.
+RATE_LIMIT_IP_HEADERS='x-forwarded-for'
+# @feature:end
+
+# @feature:start feature-flags
+GROWTHBOOK_API_HOST=''
+GROWTHBOOK_CLIENT_KEY=''
+# @feature:end

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

@@ -0,0 +1,75 @@
+# Copy to .env.test. Every test script is wrapped in `dotenv -e .env.test --`,
+# so this file — not .env — is what the suite runs against. Point it at the
+# test Docker stack (compose.test.yml), never at your dev database: the e2e
+# factory truncates every table between specs.
+
+APP_ENV='test'
+APP_NAME='Acme Corp Test'
+APP_HOST='0.0.0.0'
+PORT='5001'
+SERVER_HOST='http://localhost:5001'
+FRONTEND_HOST='http://localhost:3000'
+MISC_CORS_ORIGINS=''
+
+DATABASE_URL='postgresql://root:postgres@localhost:5499/main'
+
+BETTER_AUTH_SECRET='test-secret-not-used-in-production'
+BETTER_AUTH_URL='http://localhost:5001'
+BETTER_AUTH_COOKIE_DOMAIN='.lvh.me'
+BETTER_AUTH_COOKIE_PREFIX='acme-test'
+
+SUPERUSER_EMAIL='admin@example.com'
+SUPERUSER_PASSWORD='Secret@1'
+
+OAUTH_GOOGLE_CLIENT_ID=''
+OAUTH_GOOGLE_CLIENT_SECRET=''
+
+LOG_LEVEL='silent'
+
+# @feature:start openapi, queue, observability
+BASIC_AUTH_USER='admin'
+BASIC_AUTH_PASS='Secret@1'
+# @feature:end
+
+# @feature:start cache
+REDIS_HOST='localhost'
+REDIS_PORT='6399'
+REDIS_USER=''
+REDIS_PASSWORD=''
+# @feature:end
+
+# @feature:start mail
+# Never delivered — AppFactory replaces MailService with a no-op.
+SMTP_HOST='smtp.example.com'
+SMTP_PORT='465'
+SMTP_SECURE='true'
+SMTP_USER='test'
+SMTP_PASSWORD='test'
+SMTP_FROM='Acme Corp Test <no-reply@example.com>'
+SMTP_SUPPORT_EMAIL='support@example.com'
+# @feature:end
+
+# @feature:start media
+S3_REGION='us-east-1'
+S3_ENDPOINT=''
+S3_BUCKET_NAME='acme-test'
+S3_ACCESS_KEY_ID=''
+S3_SECRET_ACCESS_KEY=''
+# @feature:end
+
+# @feature:start rate-limit
+# Off in tests so a shared window cannot leak between specs.
+RATE_LIMIT_ENABLED='false'
+RATE_LIMIT_TTL='60000'
+RATE_LIMIT_MAX='120'
+RATE_LIMIT_AUTH_WINDOW='10'
+RATE_LIMIT_AUTH_MAX='100'
+RATE_LIMIT_IP_HEADERS='x-forwarded-for'
+# @feature:end
+
+# @feature:start feature-flags
+# Required by config validation but never contacted — AppFactory replaces
+# FeatureFlagService with a mock.
+GROWTHBOOK_API_HOST='http://localhost:3100'
+GROWTHBOOK_CLIENT_KEY='sdk-test'
+# @feature:end

package/templates/nest-api/files/.forgejo/workflows/build-and-push.yml

@@ -0,0 +1,41 @@
+name: Build and Push
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Docker Buildx
+        uses: docker/setup-buildx-action@v1
+
+      - name: Login to Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ secrets.REGISTRY_URL }}
+          username: ${{ secrets.DK_USER }}
+          password: ${{ secrets.DK_ACCESS_TOKEN }}
+
+      - name: Generate image tag
+        id: meta
+        run: |
+          DATE=$(date +'%y_%m_%d')
+          RAND=$(printf '%05d' "$((RANDOM % 100000))")
+          echo "TAG=${DATE}_${RAND}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and Push
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          context: .
+          tags: |
+            ${{ secrets.REGISTRY }}/${{ github.repository }}:latest
+            ${{ secrets.REGISTRY }}/${{ github.repository }}:${{ steps.meta.outputs.TAG }}

package/templates/nest-api/files/.forgejo/workflows/test-e2e.yml

@@ -0,0 +1,83 @@
+name: End-to-End Tests
+
+on:
+  pull_request:
+    branches: [ development ]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+
+    services:
+      database:
+        image: postgres:15.3
+        env:
+          POSTGRES_USER: root
+          POSTGRES_PASSWORD: Secretto123
+          POSTGRES_DB: starter-db
+        ports:
+          - 5491:5432
+        options: >-
+          --health-cmd "pg_isready -U root -d starter-db"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis:7.4.1
+        ports:
+          - 6391:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'yarn'
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Install Infisical CLI
+        run: npm install -g @infisical/cli
+
+      - name: Fetch secrets
+        env:
+          INFISICAL_TOKEN: ${{ secrets.INFISICAL_TOKEN }}
+          INFISICAL_API_URL: https://inf.aurostack.co
+        run: yarn secrets -e test
+
+      # Point the fetched env at this job's service containers. Whole-line
+      # replacements, so they apply whatever host, port or credentials the
+      # vault's test env holds.
+      - name: Fix service URLs for CI
+        run: |
+          sed -i "s|^DATABASE_URL=.*|DATABASE_URL='postgresql://root:Secretto123@database:5432/starter-db'|" .env.test
+          sed -i "s/^REDIS_HOST=.*/REDIS_HOST='redis'/" .env.test
+          sed -i "s/^REDIS_PORT=.*/REDIS_PORT='6379'/" .env.test
+
+      - name: Push database schema
+        run: yarn test:db:push
+
+      - name: Seed database
+        run: yarn test:db:seed
+
+      - name: Run integration tests
+        run: yarn test:e2e