@aurostack/stacks 0.1.0

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

@@ -0,0 +1,16 @@
+import puppeteer from 'puppeteer';
+import config from '#app/config.js';
+
+export async function launchBrowser() {
+	return await puppeteer.launch({
+		headless: true,
+		defaultViewport: null,
+		userDataDir: './tmp',
+		args: [
+			'--no-sandbox',
+			'--disable-setuid-sandbox',
+			'--disable-dev-shm-usage'
+		],
+		executablePath: config.puppeteer.executablePath
+	});
+}

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

@@ -0,0 +1,68 @@
+import moment from 'moment';
+
+export class DateUtil {
+	static parse(value: string, format = 'DD/MM/YYYY'): Date | null {
+		const parsed = moment(value, format, true);
+		return parsed.isValid() ? parsed.toDate() : null;
+	}
+
+	static today() {
+		return moment().startOf('date').toDate();
+	}
+
+	static previousDay() {
+		return moment().startOf('date').subtract(1, 'day').toDate();
+	}
+
+	static sevenDays() {
+		return moment().startOf('date').subtract(7, 'days').toDate();
+	}
+
+	static thirtyDays() {
+		return moment().startOf('date').subtract(30, 'days').toDate();
+	}
+
+	static oneYear() {
+		return moment().startOf('date').subtract(1, 'years').toDate();
+	}
+
+	static getWeeks(date: Date) {
+		return moment().diff(moment(date), 'weeks');
+	}
+
+	static diffDays(date: Date) {
+		return moment().startOf('date').diff(moment(date), 'days');
+	}
+
+	static diff(a: Date, b: Date) {
+		return a.getTime() - b.getTime();
+	}
+
+	static dayToSeconds() {
+		return 3600 * 24;
+	}
+
+	static dayToMilliseconds() {
+		return 1000 * DateUtil.dayToSeconds();
+	}
+
+	static dayOfWeek(date?: Date) {
+		const DOW_WORD: Record<number, string> = {
+			1: 'Monday',
+			2: 'Tuesday',
+			3: 'Wednesday',
+			4: 'Thursday',
+			5: 'Friday',
+			6: 'Saturday',
+			7: 'Sunday'
+		};
+
+		if (date) return DOW_WORD[moment(date.toISOString()).isoWeekday()];
+		return DOW_WORD[moment().isoWeekday()];
+	}
+
+	static isWeekday(date: Date) {
+		const dayOfWeek = moment(date.toISOString()).isoWeekday();
+		return dayOfWeek >= 1 && dayOfWeek <= 5;
+	}
+}

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

@@ -0,0 +1,17 @@
+import type { PaginationOptions, PaginationInfo } from '#app/types.js';
+
+/**
+ * Calculates pagination information based on the provided options
+ * @param options - pagination options for the query
+ */
+export const getPaginationInfo = (
+	options: PaginationOptions
+): PaginationInfo => {
+	const page = options.page && options.page > 0 ? options.page : 1;
+	const take = options.limit && options.limit > 0 ? options.limit : 10;
+	return {
+		skip: (page - 1) * take,
+		take,
+		page
+	};
+};

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

@@ -0,0 +1,47 @@
+import { Prisma } from '#prisma/client.js';
+import type { RawValue } from '#app/types.js';
+
+export class NumberUtil {
+	static parse(rawValue: RawValue): number | null {
+		if (rawValue === null || rawValue === undefined) return null;
+		if (typeof rawValue === 'number') return rawValue;
+		if (rawValue.trim() === '') return null;
+		const value = Number(rawValue.replace(/,/g, '').trim());
+		return Number.isFinite(value) ? value : null;
+	}
+
+	static toNumber(rawValue: RawValue) {
+		if (rawValue === null || rawValue === undefined) return 0;
+		if (typeof rawValue === 'number') return rawValue;
+		if (rawValue.trim() === '') return 0;
+		const value = Number(rawValue.replace(/,/g, '').trim());
+		return Number.isFinite(value) ? value : 0;
+	}
+
+	static toDecimal(rawValue: RawValue | Prisma.Decimal) {
+		if (rawValue instanceof Prisma.Decimal) return rawValue;
+		return new Prisma.Decimal(NumberUtil.toNumber(rawValue));
+	}
+
+	static firstPositive(
+		...values: (RawValue | Prisma.Decimal)[]
+	): Prisma.Decimal | undefined {
+		for (const value of values) {
+			const d = NumberUtil.toDecimal(value);
+			if (d.gt(0)) return d;
+		}
+		return undefined;
+	}
+
+	static maxDecimal(...vals: (Prisma.Decimal | undefined)[]): Prisma.Decimal {
+		return vals
+			.filter((v): v is Prisma.Decimal => !!v)
+			.reduce((a, b) => (b.gt(a) ? b : a));
+	}
+
+	static minDecimal(...vals: (Prisma.Decimal | undefined)[]): Prisma.Decimal {
+		return vals
+			.filter((v): v is Prisma.Decimal => !!v)
+			.reduce((a, b) => (b.lt(a) ? b : a));
+	}
+}

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

@@ -0,0 +1,29 @@
+import { Worker, type WorkerOptions, type Processor } from 'bullmq';
+import config from '#app/config.js';
+
+export const createWorker = <
+	DataType = unknown,
+	ResultType = unknown,
+	NameType extends string = string
+>(
+	name: string,
+	processor: Processor<DataType, ResultType, NameType>,
+	opts?: Omit<WorkerOptions, 'connection' | 'concurrency' | 'autorun'>
+) => {
+	const connection = {
+		host: config.redis.host,
+		port: config.redis.port,
+		user: config.redis.user,
+		password: config.redis.password
+	};
+
+	const defaultOptions = {
+		concurrency: 1,
+		autorun: false
+	};
+
+	const options = !opts
+		? { connection, ...defaultOptions }
+		: { connection, ...defaultOptions, ...opts };
+	return new Worker(name, processor, options);
+};

package/templates/node-worker/files/src/workers/constants.ts

@@ -0,0 +1,6 @@
+/**
+ * Queue names, shared with whatever produces the jobs. A worker listening on a
+ * name nothing produces to simply idles forever — there is no error — so keep
+ * these in step with the producer.
+ */
+export const EXAMPLE_QUEUE = 'example';

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

@@ -0,0 +1,27 @@
+import type { Job } from 'bullmq';
+import logger from '#app/logger.js';
+import { createWorker } from '#utils/worker.js';
+import { EXAMPLE_QUEUE } from '#app/workers/constants.js';
+
+type ExampleJob = { id: string };
+
+/**
+ * Workers are created with `autorun: false` and started explicitly from
+ * `src/index.ts`, so nothing begins consuming while the process is still wiring
+ * itself up.
+ */
+export const example = createWorker<ExampleJob>(
+	EXAMPLE_QUEUE,
+	async (job: Job<ExampleJob>) => {
+		logger.info({ jobId: job.id, data: job.data }, 'Processing job');
+
+		// Do the work here. Throwing marks the job failed and lets BullMQ retry it
+		// according to the producer's attempts/backoff settings — so throw on a
+		// genuine failure rather than swallowing it and returning normally.
+
+		// Report progress as the work advances; the dashboard and producers see it.
+		await job.updateProgress(100);
+
+		return { ok: true };
+	}
+);

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

@@ -0,0 +1 @@
+export { example } from './example/index.js';

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

@@ -0,0 +1,30 @@
+{
+	"compilerOptions": {
+		"rootDir": "./",
+		"outDir": "./dist",
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"target": "esnext",
+		"lib": ["esnext"],
+		"types": ["node"],
+		"sourceMap": false,
+		"declaration": false,
+		"declarationMap": false,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"strict": true,
+		"jsx": "react-jsx",
+		"verbatimModuleSyntax": true,
+		"isolatedModules": true,
+		"noUncheckedSideEffectImports": true,
+		"moduleDetection": "force",
+		"skipLibCheck": true,
+		"paths": {
+			"#app/*": ["./src/*"],
+			"#prisma/*": ["./prisma/generated/*"],
+			"#utils/*": ["./src/utils/*"],
+			"#lib/*": ["./src/lib/*"],
+		}
+	},
+	"include": ["src", "prisma/generated", "prisma.config.ts"],
+}

package/templates/node-worker/template.json

@@ -0,0 +1,135 @@
+{
+	"name": "node-worker",
+	"version": "0.1.0",
+	"title": "Node background worker",
+	"description": "A standalone TypeScript worker: BullMQ consumers, Prisma against the same database as your API, pino logging, and PM2 + Docker for deployment. For jobs that should not share a process with the HTTP server — scrapers, schedulers, long-running imports.",
+	"aliasRoots": {
+		"#app/": "src/",
+		"#utils/": "src/utils/",
+		"#lib/": "src/lib/",
+		"#prisma/": null
+	},
+	"generatedPaths": [
+		"prisma/generated/**",
+		"prisma/generated"
+	],
+	"replacements": [
+		{
+			"from": "Acme Corp",
+			"to": "{{Name}}"
+		},
+		{
+			"from": "collector",
+			"to": "{{name}}"
+		},
+		{
+			"from": "acme",
+			"to": "{{name}}"
+		}
+	],
+	"features": {
+		"prisma": {
+			"title": "Prisma database access",
+			"description": "Shares the schema with your API, so the worker reads and writes the same models rather than going through HTTP.",
+			"core": true
+		},
+		"logging": {
+			"title": "pino structured logging",
+			"core": true
+		},
+		"queue": {
+			"title": "BullMQ consumers",
+			"description": "Worker processes pulling from the same Redis queues your API produces to.",
+			"default": true,
+			"files": [
+				"src/utils/worker.ts",
+				"src/workers/**"
+			],
+			"packageJson": {
+				"dependencies": [
+					"bullmq"
+				]
+			}
+		},
+		"browser": {
+			"title": "Headless browser (Puppeteer)",
+			"description": "For scraping pages that need JavaScript executed. Heavy — the Docker image grows by roughly 800 MB (Chromium and its fonts).",
+			"files": [
+				"src/utils/browser.ts"
+			],
+			"packageJson": {
+				"dependencies": [
+					"puppeteer"
+				]
+			}
+		},
+		"pm2": {
+			"title": "PM2 process manager",
+			"description": "ecosystem.config.cjs for running the worker under PM2 outside Docker.",
+			"default": true,
+			"files": [
+				"ecosystem.config.cjs"
+			]
+		},
+		"docker": {
+			"title": "Docker image",
+			"default": true,
+			"files": [
+				"Dockerfile",
+				"Dockerfile.dev",
+				".dockerignore"
+			]
+		},
+		"ci": {
+			"title": "Forgejo Actions CI",
+			"default": true,
+			"files": [
+				".forgejo/**"
+			]
+		},
+		"secrets": {
+			"title": "Infisical secret sync",
+			"default": true,
+			"files": [
+				".bin/secrets.ts"
+			],
+			"packageJson": {
+				"scripts": [
+					"secrets"
+				]
+			}
+		}
+	},
+	"hooks": [
+		{
+			"title": "seed .env",
+			"run": "cp -n .env.example .env || true",
+			"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 node-worker template'",
+			"optional": true
+		}
+	],
+	"nextSteps": [
+		"Bring in the API's Prisma models: copy its prisma/schema/*.prisma beside prisma/schema/base.prisma, or share one schema via a submodule.",
+		"Edit .env — DATABASE_URL and REDIS_* must match the API's.",
+		"yarn db:generate && yarn dev"
+	]
+}

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

@@ -0,0 +1,176 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.vscode/
+
+test.py
+
+input/*
+!input/.gitkeep
+
+output/*
+!output/.gitkeep
+
+logs/*
+!logs/.gitkeep

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

@@ -0,0 +1,20 @@
+# Copy to .env.
+
+# Absolute path to this project. input/, output/ and logs/ are resolved
+# beneath it, so a relative value silently writes to the wrong place.
+HOME_PATH=""
+
+# The same database your API owns. The SQLAlchemy models here are hand-written
+# and must be kept in step with its schema by hand — nothing checks this.
+DB_HOST="localhost"
+DB_PORT=5432
+DB_USER="root"
+DB_PASSWORD="postgres"
+DB_NAME="main"
+
+# The same Redis your API produces jobs to. A mismatch is silent: the worker
+# connects fine and simply never receives anything.
+REDIS_HOST="localhost"
+REDIS_PORT=6379
+REDIS_USER=
+REDIS_PASSWORD=""

package/templates/py-worker/files/.forgejo/workflows/build-amd-push.yml

@@ -0,0 +1,39 @@
+name: Build and Push
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - 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/py-worker/files/Dockerfile

@@ -0,0 +1,10 @@
+FROM aurostack.dev/wesnetech/python:3.14
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["python", "worker.py"]

package/templates/py-worker/files/README.md

@@ -0,0 +1,3 @@
+# py
+
+Support backend with process-heavy background jobs, run one-off tasks, handle data collection tasks etc.