@aurostack/stacks 0.1.0

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

@@ -0,0 +1,21 @@
+# Copy to .env.
+
+APP_ENV='development'
+LOG_LEVEL='debug'
+
+# The same database your API uses — this worker talks to it directly rather
+# than over HTTP, so the schema must match.
+DATABASE_URL='postgresql://root:postgres@localhost:5432/main'
+
+# The same Redis your API produces jobs to. A mismatch here is silent: the
+# worker connects fine and simply never receives anything.
+REDIS_HOST='localhost'
+REDIS_PORT='6379'
+REDIS_USER=''
+REDIS_PASSWORD=''
+
+# @feature:start browser
+# Empty = use Puppeteer's bundled Chromium. Set this in a slim container image
+# where Chromium is installed separately.
+PUPPETEER_EXECUTABLE_PATH=''
+# @feature:end

package/templates/node-worker/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/node-worker/files/.nvmrc

@@ -0,0 +1 @@
+24.16

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

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+tmp/
+yarn.lock

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

@@ -0,0 +1,8 @@
+{
+	"useTabs": true,
+	"arrowParens": "always",
+	"tabWidth": 2,
+	"singleQuote": true,
+	"semi": true,
+	"trailingComma": "none"
+}

package/templates/node-worker/files/.yarnrc.yml

@@ -0,0 +1,5 @@
+# Prisma places its engine binaries inside node_modules and cannot do so under
+# Yarn's default PnP linker — `prisma generate` fails with EROFS on a path
+# outside the project. Everything else here works under PnP; this one does not.
+nodeLinker: node-modules
+enableTelemetry: false

package/templates/node-worker/files/Dockerfile

@@ -0,0 +1,63 @@
+# Stage 1: Build
+FROM aurostack.dev/wesnetech/nodejs:24 AS build
+
+# @feature:start browser
+# Chromium comes from apk in the runtime stage; don't download a second copy.
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+# @feature:end
+
+WORKDIR /app
+
+# The image bundles Yarn 1.x; corepack switches to the Yarn 4 release pinned by
+# package.json's `packageManager`, which is what can read yarn.lock.
+RUN corepack enable
+
+# yarn.lock and .yarnrc.yml must both land here: --immutable requires a lockfile,
+# and without .yarnrc.yml Yarn uses PnP, which Prisma cannot generate under.
+COPY package.json yarn.lock .yarnrc.yml ./
+# Long timeout, one request at a time: tolerant of a slow or flaky registry.
+RUN YARN_HTTP_TIMEOUT=300000 YARN_NETWORK_CONCURRENCY=1 yarn install --immutable
+
+COPY tsconfig*.json prisma.config.ts ./
+COPY .bin ./.bin
+COPY prisma ./prisma
+RUN yarn db:generate
+
+COPY src ./src
+RUN yarn build
+
+# Remove dev dependencies after build is done. Yarn 4 has no
+# `install --production`; focusing the root workspace is its equivalent.
+RUN yarn workspaces focus --all --production
+
+# Stage 2: Production
+FROM aurostack.dev/wesnetech/nodejs:24
+WORKDIR /app
+
+# @feature:start browser
+RUN apk add --no-cache \
+	chromium \
+	nss \
+	freetype \
+	harfbuzz \
+	ca-certificates \
+	ttf-freefont \
+	udev
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
+	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+# @feature:end
+
+COPY package.json ./
+# @feature:start pm2
+COPY ecosystem.config.cjs ./
+# @feature:end
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+
+# @feature:start pm2
+# pm2-runtime ships in the base image.
+CMD [ "pm2-runtime", "start", "ecosystem.config.cjs" ]
+# @feature:else
+CMD [ "node", "dist/src/index.js" ]
+# @feature:end

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

@@ -0,0 +1,59 @@
+# Stage 1: Build
+FROM aurostack.dev/wesnetech/nodejs:24 AS build
+
+# @feature:start browser
+# Chromium comes from apk in the runtime stage; don't download a second copy.
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+# @feature:end
+
+WORKDIR /app
+
+# The image bundles Yarn 1.x; corepack switches to the Yarn 4 release pinned by
+# package.json's `packageManager`, which is what can read yarn.lock.
+RUN corepack enable
+
+# yarn.lock and .yarnrc.yml must both land here: --immutable requires a lockfile,
+# and without .yarnrc.yml Yarn uses PnP, which Prisma cannot generate under.
+COPY package.json yarn.lock .yarnrc.yml ./
+# Long timeout, one request at a time: tolerant of a slow or flaky registry.
+RUN YARN_HTTP_TIMEOUT=300000 YARN_NETWORK_CONCURRENCY=1 yarn install --immutable
+
+COPY tsconfig*.json prisma.config.ts ./
+COPY .bin ./.bin
+COPY prisma ./prisma
+RUN yarn db:generate
+
+COPY src ./src
+RUN yarn build
+
+# Stage 2: Production
+FROM aurostack.dev/wesnetech/nodejs:24
+WORKDIR /app
+
+# @feature:start browser
+RUN apk add --no-cache \
+	chromium \
+	nss \
+	freetype \
+	harfbuzz \
+	ca-certificates \
+	ttf-freefont \
+	udev
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
+	PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+# @feature:end
+
+COPY package.json ./
+# @feature:start pm2
+COPY ecosystem.config.cjs ./
+# @feature:end
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+
+# @feature:start pm2
+# pm2-runtime ships in the base image.
+CMD [ "pm2-runtime", "start", "ecosystem.config.cjs" ]
+# @feature:else
+CMD [ "node", "dist/src/index.js" ]
+# @feature:end

package/templates/node-worker/files/_gitignore

@@ -0,0 +1,48 @@
+# compiled output
+/dist
+/node_modules
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+.env
+.env.test
+.env.production
+.npmrc
+docker-compose.dev.yaml
+
+package-lock.json
+
+docs/
+prisma/schema.dbml
+
+tmp/

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

@@ -0,0 +1,10 @@
+module.exports = {
+  apps : [
+		{
+			name: 'collector',
+			script: 'dist/src/index.js',
+			watch: false,
+			autorestart: false,
+		}
+	],
+};

package/templates/node-worker/files/eslint.config.js

@@ -0,0 +1,37 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettier from 'eslint-config-prettier';
+import globals from 'globals';
+
+export default tseslint.config(
+	{
+		ignores: ['node_modules/', 'dist/', 'tmp/', 'ecosystem.config.cjs'],
+	},
+	js.configs.recommended,
+	...tseslint.configs.recommendedTypeChecked.map((config) => ({
+		...config,
+		files: ['src/**/*.ts'],
+	})),
+	{
+		files: ['src/**/*.ts'],
+		languageOptions: {
+			globals: globals.node,
+			parserOptions: {
+				projectService: true,
+				tsconfigRootDir: import.meta.dirname,
+			},
+		},
+		rules: {
+			'@typescript-eslint/no-unused-vars': ['warn'],
+			'@typescript-eslint/no-explicit-any': ['off'],
+			'@typescript-eslint/no-unsafe-call': ['off'],
+			'@typescript-eslint/no-unsafe-member-access': ['off'],
+			'@typescript-eslint/no-unsafe-argument': ['off'],
+			'@typescript-eslint/no-unsafe-enum-comparison': ['off'],
+			'@typescript-eslint/no-unsafe-return': ['off'],
+			'@typescript-eslint/no-unsafe-assignment': ['off'],
+			'@typescript-eslint/no-redundant-type-constituents': ['off'],
+		}
+	},
+	prettier,
+);

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

@@ -0,0 +1,67 @@
+{
+	"name": "collector",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "dist/src/index.js",
+	"license": "MIT",
+	"packageManager": "yarn@4.14.1",
+	"imports": {
+		"#app/*": {
+			"development": "./src/*",
+			"default": "./dist/src/*"
+		},
+		"#prisma/*": {
+			"development": "./prisma/generated/*",
+			"default": "./dist/prisma/generated/*"
+		},
+		"#utils/*": {
+			"development": "./src/utils/*",
+			"default": "./dist/src/utils/*"
+		},
+		"#lib/*": {
+			"development": "./src/lib/*",
+			"default": "./dist/src/lib/*"
+		}
+	},
+	"scripts": {
+		"dev": "tsx --conditions=development src/index.ts",
+		"dev:watch": "tsx watch --conditions=development src/index.ts",
+		"build": "tsc",
+		"start": "node dist/src/index.js",
+		"secrets": "tsx --conditions=development .bin/secrets",
+		"db:generate": "tsx --conditions=development ./.bin/db.ts",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint .",
+		"lint:fix": "eslint . --fix",
+		"format": "prettier --write .",
+		"format:check": "prettier --check ."
+	},
+	"dependencies": {
+		"@paralleldrive/cuid2": "^3.3.0",
+		"@prisma/adapter-pg": "^7.8.0",
+		"@prisma/client": "^7.8.0",
+		"bullmq": "^5.79.2",
+		"dotenv": "^17.4.2",
+		"moment": "^2.30.1",
+		"pino": "^10.3.1",
+		"puppeteer": "^25.3.0",
+		"shelljs": "^0.10.0",
+		"yargs": "^18.0.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^26.1.0",
+		"@types/shelljs": "^0.10.0",
+		"@types/yargs": "^17.0.35",
+		"eslint": "^10.6.0",
+		"eslint-config-prettier": "^10.1.8",
+		"globals": "^17.7.0",
+		"pino-pretty": "^13.1.3",
+		"prettier": "^3.9.4",
+		"prisma": "^7.8.0",
+		"prisma-dbml-generator": "^0.12.0",
+		"tsx": "^4.22.4",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.62.1"
+	}
+}

package/templates/node-worker/files/prisma/_gitignore

@@ -0,0 +1 @@
+generated/

package/templates/node-worker/files/prisma/schema/base.prisma

@@ -0,0 +1,36 @@
+// Datasource + generators only.
+//
+// This worker ships a single placeholder model (below). It reads and writes the same
+// database your API owns, so the schema belongs there — copy the API's
+// `prisma/schema/*.prisma` in beside this file, or (better) point both repos at
+// one shared schema via a git submodule, so a migration on one side cannot
+// leave the other compiling against columns that no longer exist.
+//
+// `yarn db:generate` writes the client to `prisma/generated`, which the
+// `#prisma/*` subpath import in package.json resolves to.
+
+datasource db {
+  provider = "postgresql"
+}
+
+generator client {
+  provider     = "prisma-client"
+  output       = "../generated"
+  moduleFormat = "esm"
+}
+
+/// Placeholder so `prisma generate` emits a usable client on a fresh scaffold —
+/// a model-less schema generates nothing, and every `#prisma/client.js` import
+/// then fails to resolve.
+///
+/// It is `User` with an `email` specifically because `src/db.ts` ships
+/// `findById` / `findByEmail` client extensions typed against this model.
+/// Replace it with the API's real `User` (and the rest of its schema) rather
+/// than deleting it outright, or those extensions stop compiling.
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@map("user")
+}

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

@@ -0,0 +1,13 @@
+import 'dotenv/config';
+import { defineConfig } from 'prisma/config';
+
+export default defineConfig({
+	schema: 'prisma/schema',
+	// migrations: {
+	// 	path: 'prisma/migrations',
+	// 	seed: 'ts-node prisma/seeders'
+	// },
+	datasource: {
+		url: process.env['DATABASE_URL'] || ''
+	}
+});

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

@@ -0,0 +1,55 @@
+import 'dotenv/config';
+
+interface App {
+	env: string;
+	logLevel: string;
+}
+
+interface Database {
+	url: string;
+}
+
+interface Redis {
+	host: string;
+	port: number;
+	user?: string | undefined;
+	password?: string | undefined;
+}
+
+// @feature:start browser
+interface Puppeteer {
+	executablePath: string;
+}
+// @feature:end
+
+interface Config {
+	app: App;
+	database: Database;
+	redis: Redis;
+	puppeteer: Puppeteer; // @feature browser
+}
+
+const config: Config = {
+	app: {
+		env: process.env.APP_ENV ?? 'development',
+		logLevel: process.env.LOG_LEVEL ?? 'debug'
+	},
+	database: {
+		url: process.env.DATABASE_URL ?? ''
+	},
+	redis: {
+		host: process.env.REDIS_HOST ?? 'localhost',
+		port: parseInt(process.env.REDIS_PORT ?? '6379', 10),
+		user: process.env.REDIS_USER,
+		password: process.env.REDIS_PASSWORD
+	},
+	// @feature:start browser
+	// Empty means "let Puppeteer use its bundled Chromium". In a slim container
+	// image you install Chromium separately and point this at it.
+	puppeteer: {
+		executablePath: process.env.PUPPETEER_EXECUTABLE_PATH ?? ''
+	}
+	// @feature:end
+};
+
+export default config;

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

@@ -0,0 +1,118 @@
+import { PrismaPg } from '@prisma/adapter-pg';
+import config from '#app/config.js';
+import { Prisma, PrismaClient } from '#prisma/client.js';
+import type { PaginationOptions, PaginationMetaData } from '#app/types.js';
+import { getPaginationInfo } from '#app/utils/helpers.js';
+
+interface FindByEmailOptions {
+	email: string;
+	mode?: 'default' | 'insensitive' | undefined;
+}
+
+const setupExtensions = (db: PrismaClient) =>
+	db.$extends({
+		model: {
+			$allModels: {
+				async exists<
+					Type,
+					Arguments,
+					Result extends Prisma.Result<Type, Arguments, 'count'>
+				>(this: Type, where: Prisma.Args<Type, 'count'>['where']) {
+					const ctx = Prisma.getExtensionContext(this) as any;
+					const counts: Result = await ctx.count({ where });
+					return Boolean(counts);
+				},
+				async paginate<
+					Type,
+					Args extends Omit<
+						Prisma.Args<Type, 'findMany'>,
+						'skip' | 'take' | 'cursor'
+					>,
+					Result extends Prisma.Result<Type, Args, 'findMany'>
+				>(this: Type, args: Args & PaginationOptions) {
+					const { limit, page, where, ...rest } = args;
+					const {
+						skip,
+						take,
+						page: currentPage
+					} = getPaginationInfo({
+						limit,
+						page
+					});
+					const ctx = Prisma.getExtensionContext(this) as any;
+					const [list, total]: [Result, number] = await Promise.all([
+						ctx.findMany({ ...rest, skip, take, where }),
+						ctx.count({ where })
+					]);
+					const meta: PaginationMetaData = {
+						total,
+						currentPage,
+						pageSize: list.length,
+						lastPage: Math.ceil(total / take) || 1
+					};
+					const result: [Result, PaginationMetaData] = [list, meta];
+					return result;
+				}
+			},
+			user: {
+				async findById<
+					Type,
+					Args extends Omit<Prisma.UserFindUniqueArgs, 'where'>,
+					Result extends Prisma.Result<Type, Args, 'findUnique'>
+				>(this: Type, id: string, args?: Args): Promise<Result> {
+					const ctx = Prisma.getExtensionContext(this) as any;
+					return await ctx.findUnique({
+						where: { id },
+						...args
+					});
+				},
+				async findByEmail<
+					Type,
+					Args extends Omit<Prisma.UserFindFirstArgs, 'where'>,
+					Result extends Prisma.Result<Type, Args, 'findFirst'>
+				>(
+					this: Type,
+					{ email, mode }: FindByEmailOptions,
+					args?: Args
+				): Promise<Result> {
+					const ctx = Prisma.getExtensionContext(this) as any;
+					return await ctx.findFirst({
+						where: { email: { equals: email, mode: mode || 'default' } },
+						...args
+					});
+				}
+			}
+		}
+	});
+
+export class DB extends PrismaClient {
+	static #instance: DB | null = null;
+
+	private constructor() {
+		const connectionString = config.database.url;
+		const adapter = new PrismaPg({ connectionString });
+		super({ adapter });
+	}
+
+	public static getInstance(): DB {
+		if (!DB.#instance) {
+			DB.#instance = new DB();
+		}
+		return DB.#instance;
+	}
+
+	public static get instance() {
+		return DB.getInstance();
+	}
+
+	/**
+	 * Extended version of client with custom methods, etc.
+	 */
+	get $() {
+		return setupExtensions(this);
+	}
+
+	async disconnect() {
+		await this.$disconnect();
+	}
+}

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

@@ -0,0 +1,7 @@
+import logger from '#app/logger.js';
+import * as Workers from '#app/workers/index.js'; // @feature queue
+
+(() => {
+	logger.info('Worker started');
+	void Workers.example.run(); // @feature queue
+})();

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

@@ -0,0 +1,45 @@
+import pino, { stdTimeFunctions, levels } from 'pino';
+import config from '#app/config.js';
+
+const PINO_CONSOLE_TARGET = {
+	target: 'pino-pretty',
+	options: {
+		ignore: 'pid,hostname',
+		translateTime: 'SYS:dd-mm-yyyy HH:MM:ss',
+		singleLine: true,
+		colorize: true
+	}
+};
+
+const PINO_FILE_TARGET = {
+	target: 'pino/file',
+	options: {
+		destination: 'logs/collector.log',
+		mkdir: true
+	}
+};
+
+const PINO_CONSOLE_TARGET_PROD = {
+	target: 'pino/file',
+	options: {
+		destination: 1
+	}
+};
+
+const logger = pino({
+	level: config.app.logLevel,
+	transport:
+		config.app.env === 'production'
+			? { targets: [PINO_CONSOLE_TARGET_PROD, PINO_FILE_TARGET] }
+			: { targets: [PINO_CONSOLE_TARGET, PINO_FILE_TARGET] },
+	base: {
+		service: 'collector',
+		env: config.app.env
+	},
+	timestamp: stdTimeFunctions.isoTime,
+	mixin(_mergeObject, level) {
+		return { levelLabel: levels.labels[level] };
+	}
+});
+
+export default logger;

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

@@ -0,0 +1,23 @@
+export interface PaginationOptions {
+	page?: number | undefined;
+	limit?: number | undefined;
+}
+
+export interface PaginationInfo {
+	skip: number;
+	take: number;
+	page: number;
+}
+
+export interface PaginationMetaData {
+	total: number;
+	pageSize: number;
+	currentPage: number;
+	lastPage: number;
+}
+
+export interface Paginated<T> extends PaginationMetaData {
+	list: T[];
+}
+
+export type RawValue = string | number | null | undefined;