@aurostack/stacks 0.1.0

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

@@ -0,0 +1,41 @@
+import os
+from bullmq import Worker
+import asyncio
+import signal
+from utils.logger import Logger
+from utils.worker import create_worker
+
+# import worker processes
+from workers.hello.process import hello_process
+logger = Logger("worker")
+
+
+async def main():
+    logger.info("Starting Python 3.14 Worker...")
+    shutdown_event = asyncio.Event()
+    loop = asyncio.get_running_loop()
+
+    # Async signal handlers
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(
+            sig,
+            lambda s=sig: (
+                logger.info(f"Signal {s} received, shutting down."),
+                shutdown_event.set()
+            ),
+        )
+
+    # Add workers
+    hello = create_worker("hello", hello_process)
+
+    logger.info("Workers started and waiting for jobs.")
+    try:
+        await shutdown_event.wait()
+    finally:
+        logger.info("Cleaning up workers...")
+        # Close workers gracefully
+        await hello.close()
+        logger.info("Workers shut down successfully.")
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/templates/py-worker/files/workers/hello/process.py

@@ -0,0 +1,22 @@
+from bullmq import Job
+
+from utils.worker import create_logger, JobUtil
+
+logger = create_logger('hello')
+
+
+async def hello_process(job: Job, job_token):
+    """
+    Job handler.
+
+    Raising marks the job failed and lets BullMQ retry it according to the
+    producer's attempts/backoff settings — so raise on a genuine failure rather
+    than swallowing it and returning normally.
+    """
+    util = JobUtil(job, logger)
+    logger.info(f"Job[{job.id}]: processing... (token={job_token})")
+    await util.process_log("Processing started")
+
+    # Do the work here.
+
+    await util.finalize()

package/templates/py-worker/template.json

@@ -0,0 +1,87 @@
+{
+	"name": "py-worker",
+	"version": "0.1.0",
+	"title": "Python background worker",
+	"description": "A Python BullMQ worker that consumes the same Redis queues your Node API produces to, with SQLAlchemy models over the same Postgres database, structured logging and graceful shutdown. For work that belongs in Python — data processing, ML, scientific libraries.",
+	"aliasRoots": {},
+	"generatedPaths": [
+		"**/__pycache__/**"
+	],
+	"replacements": [
+		{
+			"from": "Acme Corp",
+			"to": "{{Name}}"
+		},
+		{
+			"from": "acme",
+			"to": "{{name}}"
+		}
+	],
+	"features": {
+		"queue": {
+			"title": "BullMQ consumers",
+			"description": "Workers pulling from the same Redis queues your Node API produces to, with graceful SIGINT/SIGTERM shutdown.",
+			"core": true
+		},
+		"logging": {
+			"title": "Structured logging",
+			"core": true
+		},
+		"database": {
+			"title": "SQLAlchemy over Postgres",
+			"description": "Direct database access to the same schema your API owns. Models are hand-written here rather than generated, so they must be kept in step with the Prisma schema by hand.",
+			"default": true,
+			"files": [
+				"utils/db.py",
+				"models/**"
+			],
+			"requirements": [
+				"SQLAlchemy",
+				"psycopg2-binary",
+				"greenlet"
+			]
+		},
+		"docker": {
+			"title": "Docker image",
+			"default": true,
+			"files": [
+				"Dockerfile",
+				".dockerignore"
+			]
+		},
+		"ci": {
+			"title": "Forgejo Actions CI",
+			"default": true,
+			"files": [
+				".forgejo/**"
+			]
+		}
+	},
+	"hooks": [
+		{
+			"title": "seed .env",
+			"run": "cp -n .env.example .env || true",
+			"optional": true
+		},
+		{
+			"title": "create a virtualenv",
+			"run": "python3 -m venv .venv",
+			"optional": true
+		},
+		{
+			"title": "install requirements",
+			"run": ".venv/bin/pip install -q -r requirements.txt",
+			"optional": true
+		},
+		{
+			"title": "git init",
+			"run": "git init -q && git add -A && git commit -qm 'chore: scaffold {{name}} from the py-worker template'",
+			"optional": true
+		}
+	],
+	"nextSteps": [
+		"Edit .env — DB_* and REDIS_* must match the API's.",
+		"source .venv/bin/activate",
+		"python worker.py"
+	]
+}

package/templates/react-app/README.md

@@ -0,0 +1,78 @@
+# react-app
+
+The `react-monorepo` stack collapsed into a single Vite app: one build, one
+image, one origin.
+
+```
+stack new react-app ~/Projects/acme/web --with marketing,admin
+```
+
+## Layout of a generated project
+
+```
+src/
+├── main.tsx
+├── app/            providers · router · store · nav
+├── lib/            env · paths
+├── shared/         ui · api · auth · layouts · hooks · types
+├── features/       auth (screens' components + actions) · seo
+└── routes/         home · settings · auth/* · legal/* · marketing/* · admin/*
+```
+
+`@/` resolves to `src/` (Vite alias + tsconfig `paths`), so `@/shared/ui` is
+what `@scope/ui` was in the monorepo. Nothing else about the code changes.
+
+## Where it deliberately differs from the monorepo
+
+One origin instead of four, which changes three things and nothing else:
+
+- **The session guard navigates.** `ProtectedRoute` renders `<Navigate to="/login?redirect=…" replace />`
+  rather than assigning `window.location`. The login screen is in this same
+  bundle, so a full page load would re-download and re-boot the app to show a
+  screen it already has. The 401 handler still does a hard load, because it fires
+  from outside React and discarding in-memory state is the point there.
+- **`trustedOrigins` defaults to this origin.** The open-redirect allowlist stays
+  — `?redirect=` is still attacker-controllable — but there is nothing to add to
+  it unless you deliberately hand off to another host.
+- **Absolute URLs come from the browser**, not from env. `APP_ORIGIN` is
+  `window.location.origin`. The only place an absolute URL is genuinely needed is
+  a link that lands in an email, and a build-time `VITE_APP_URL` can only be
+  wrong there — a stale value baked into an image sends verification links to the
+  previous environment, invisibly, until someone clicks one.
+
+## Where the app is mounted
+
+`src/lib/paths.ts` owns this. With the `marketing` feature the landing page owns
+`/` and the authenticated app moves to `/app`; without it, the app owns the root.
+The router, the nav and the post-login redirect all read `appPath()`, so they
+cannot disagree.
+
+Routes *inside* the app shell stay relative and need none of this.
+
+The legal pages (`/terms`, `/privacy`) ship either way, on purpose: the signup
+consent gate links to them, and a checkbox that says "I agree to the Terms" over
+a 404 is not consent.
+
+## Maintaining it
+
+The shared packages and the page components are the *same source* as
+`react-monorepo` — only their location and their import specifiers differ. Don't
+edit them here.
+
+```sh
+bash templates/react-app/derive.sh      # re-flatten from react-monorepo
+stack doctor react-app                  # always, afterwards
+```
+
+`derive.sh` rebuilds `src/shared`, `src/features/{auth,seo}`,
+`src/routes/{auth,marketing}` from scratch each run, then copies `overrides/` on
+top. Anything in `overrides/` is a file that genuinely differs in a monolith —
+that directory listing *is* the list of intentional divergences, and it is short
+by design.
+
+Everything else (`app/`, `lib/`, `vite.config.ts`, `package.json`, `Dockerfile`)
+is hand-written here and untouched by the script.
+
+So: a fix to a UI component or an auth screen goes into `react-monorepo` and
+arrives here on the next `derive.sh`. A fix to routing, config or the build
+belongs to whichever template it is in.

package/templates/react-app/derive.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# Re-derive the mechanically-copyable half of the react-app template from
+# react-monorepo.
+#
+# react-app is the same stack as react-monorepo collapsed into one Vite app, so
+# the shared packages and the page components are *identical source* — only their
+# location and their import specifiers differ. Rather than maintain two copies by
+# hand and watch them drift, this script re-flattens them:
+#
+#   packages/<p>/src/**               ->  src/shared/<p>/**
+#   apps/auth/src/{components,lib}/** ->  src/features/auth/**
+#   apps/auth/src/routes/**           ->  src/routes/auth/**
+#   apps/client/src/routes/**         ->  src/routes/**
+#   apps/landing/src/...              ->  src/routes/marketing/, src/features/seo/
+#
+# and rewrites `@acme/x` -> `@/shared/x`.
+#
+# A handful of files genuinely differ in a monolith — one origin means the auth
+# guard navigates instead of redirecting across hosts, and the auth screens take
+# in-app paths rather than sibling-app URLs. Those live in `overrides/` and are
+# copied over the derived tree at the end, so this script is idempotent and the
+# divergence from the monorepo is visible in one directory listing.
+#
+# Everything outside the DERIVED trees — the router, store, providers, vite
+# config, package.json, Dockerfile — is hand-written and untouched here.
+#
+# Usage:  bash templates/react-app/derive.sh
+#         stack doctor react-app          # always, afterwards
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+STACKS="$(cd "$HERE/../.." && pwd)"
+SRC="$STACKS/templates/react-monorepo/files"
+DST="$HERE/files"
+
+[ -d "$SRC" ] || { echo "missing $SRC — extract react-monorepo first" >&2; exit 1; }
+
+# Trees this script owns end to end and rebuilds from scratch every run.
+DERIVED=(
+	src/shared
+	src/features/auth
+	src/features/seo
+	src/routes/auth
+	src/routes/marketing
+)
+
+echo "==> clearing derived trees"
+for dir in "${DERIVED[@]}"; do
+	rm -rf "${DST:?}/$dir"
+done
+
+echo "==> flattening packages -> src/shared"
+mkdir -p "$DST/src/shared"
+for pkg in ui api auth layouts hooks types; do
+	cp -r "$SRC/packages/$pkg/src" "$DST/src/shared/$pkg"
+done
+# The brand tokens live in the config package in the monorepo because three
+# other packages consume them; here there is one consumer, so they sit next to
+# the stylesheet that imports them.
+cp "$SRC/packages/config/tailwind/theme.css" "$DST/src/shared/ui/styles/theme.css"
+# `packages/types/src/types/api` earns its doubled segment as a package (the
+# package is `types`, the directory of generated output is `types/api`). Flattened
+# into one app it just reads as a stutter, so it lands at `shared/types/api`.
+mv "$DST/src/shared/types/types/api" "$DST/src/shared/types/api"
+rmdir "$DST/src/shared/types/types"
+
+echo "==> flattening apps -> src/features, src/routes"
+mkdir -p "$DST/src/features/auth" "$DST/src/routes/auth" "$DST/src/routes/marketing" "$DST/src/features/seo"
+cp -r "$SRC/apps/auth/src/components" "$DST/src/features/auth/components"
+cp -r "$SRC/apps/auth/src/lib" "$DST/src/features/auth/lib"
+# `env.ts` is per-app in the monorepo (four different sets of sibling origins);
+# the monolith has exactly one, hand-written at src/lib/env.ts.
+rm -f "$DST/src/features/auth/lib/env.ts"
+cp "$SRC"/apps/auth/src/routes/*.tsx "$DST/src/routes/auth/"
+cp "$SRC"/apps/client/src/routes/*.tsx "$DST/src/routes/"
+cp "$SRC/apps/landing/src/routes/home.tsx" "$DST/src/routes/marketing/home.tsx"
+cp "$SRC/apps/landing/src/features/seo/routes.ts" "$DST/src/features/seo/routes.ts"
+
+echo "==> rewriting import specifiers"
+# Longest first: `@acme/ui/brand` must not be matched by the `@acme/ui` rule.
+# `@` resolves to `src` (vite alias + tsconfig paths), so these are valid from
+# any depth and survive a file being moved.
+find "$DST/src" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.css' \) -print0 |
+	xargs -0 sed -i \
+		-e "s#@acme/ui/theme-colors#@/shared/ui/theme/theme-colors#g" \
+		-e "s#@acme/ui/globals.css#@/shared/ui/styles/globals.css#g" \
+		-e "s#@acme/ui/brand#@/shared/ui/meta/brand#g" \
+		-e "s#@acme/types/zod#@/shared/types/api/zod.gen#g" \
+		-e "s#@acme/config/tailwind.css#./theme.css#g" \
+		-e "s#@acme/config#theme.css#g" \
+		-e "s#@acme/ui#@/shared/ui#g" \
+		-e "s#@acme/api#@/shared/api#g" \
+		-e "s#@acme/auth#@/shared/auth#g" \
+		-e "s#@acme/layouts#@/shared/layouts#g" \
+		-e "s#@acme/hooks#@/shared/hooks#g" \
+		-e "s#@acme/types#@/shared/types#g"
+
+# The auth screens moved one level deeper than their components and lib, so
+# their relative imports no longer reach. Anchor them instead.
+find "$DST/src/routes/auth" -type f -name '*.tsx' -print0 |
+	xargs -0 sed -i \
+		-e "s#'\.\./components/#'@/features/auth/components/#g" \
+		-e "s#'\.\./lib/#'@/features/auth/lib/#g"
+
+# ...which the types barrel points at.
+sed -i -e "s#'\./types/api#'./api#g" -e "s#under \./types/api#under ./api#" "$DST/src/shared/types/index.ts"
+
+# Package barrels name themselves in their header comment.
+find "$DST/src/shared" -type f -name 'index.ts' -print0 |
+	xargs -0 sed -i -e "s#^// @acme/\([a-z]*\) —#// @/shared/\1 —#"
+
+echo "==> applying monolith overrides"
+# One origin, one router: these files diverge from the monorepo on purpose.
+# `cp -v` so the list is visible in the output — if one of these ever stops
+# corresponding to a real derived file, it shows up here as a new path rather
+# than silently doing nothing.
+(cd "$HERE/overrides" && find . -type f -print0) |
+	while IFS= read -r -d '' rel; do
+		target="$DST/${rel#./}"
+		[ -f "$target" ] || echo "  NOTE: override has no derived counterpart: ${rel#./}"
+		mkdir -p "$(dirname "$target")"
+		cp "$HERE/overrides/${rel#./}" "$target"
+		echo "  ${rel#./}"
+	done
+
+echo
+echo "done. Now run:  node $STACKS/cli/stack.mjs doctor react-app"

package/templates/react-app/files/.bin/openapi.js

@@ -0,0 +1,32 @@
+import 'dotenv/config';
+import ti from 'tiny-invariant';
+import axios from 'axios';
+import fs from 'fs/promises';
+
+const loadSchema = async () => {
+	const apiDocUrl = process.env.API_DOC_URL;
+	const username = process.env.API_DOC_USER;
+	const password = process.env.API_DOC_PASSWORD;
+
+	ti(apiDocUrl, 'API_DOC_URL is required');
+	ti(username, 'API_DOC_USER is required');
+	ti(password, 'API_DOC_PASSWORD is required');
+
+	const response = await axios.get(apiDocUrl, {
+		auth: {
+			username,
+			password
+		}
+	});
+
+	return response.data;
+};
+
+(async () => {
+	const schema = await loadSchema();
+	await fs.writeFile('openapi.json', JSON.stringify(schema), 'utf-8');
+	console.log('💾 Wrote openapi.json');
+})().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/templates/react-app/files/.bin/secrets.js

@@ -0,0 +1,47 @@
+import { execSync } from 'node:child_process';
+
+// Pulls this app's env from Infisical into the matching .env file.
+//
+// The project ID is read from the environment rather than hardcoded: it
+// identifies one organisation's vault, so a value baked in here would follow
+// every copy of this scaffold to projects it has nothing to do with. Put it in
+// your shell profile, or in a committed `.infisical.json`.
+const PROJECT_ID = process.env.INFISICAL_PROJECT_ID;
+const SECRET_PATH = process.env.INFISICAL_PATH ?? '/';
+
+const ENV_FILES = {
+	dev: '.env',
+	test: '.env.test',
+	staging: '.env.staging',
+	prod: '.env.production'
+};
+
+const normalizeEnv = (raw) => {
+	if (['dev', 'development'].includes(raw)) return 'dev';
+	if (['test', 'testing'].includes(raw)) return 'test';
+	if (['prod', 'production'].includes(raw)) return 'prod';
+	if (raw === 'staging') return 'staging';
+	throw new Error(`Unknown env '${raw}' (use one of: dev, test, staging, prod)`);
+};
+
+const parseEnvArg = () => {
+	const args = process.argv.slice(2);
+	const flagIndex = args.findIndex((a) => a === '-e' || a === '--env');
+	if (flagIndex !== -1 && args[flagIndex + 1]) return args[flagIndex + 1];
+	const inline = args.find((a) => a.startsWith('--env='));
+	if (inline) return inline.slice('--env='.length);
+	return 'development';
+};
+
+if (!PROJECT_ID) {
+	console.error('INFISICAL_PROJECT_ID is not set — nothing to fetch from.');
+	process.exit(1);
+}
+
+const env = normalizeEnv(parseEnvArg());
+const envFile = ENV_FILES[env];
+
+console.log(`Fetching secrets (${env}) -> ${envFile}...`);
+execSync(`infisical export --projectId="${PROJECT_ID}" --path="${SECRET_PATH}" --env=${env} > ${envFile}`, {
+	stdio: 'inherit'
+});

package/templates/react-app/files/.dockerignore

@@ -0,0 +1,16 @@
+# Keep the build context small and the image reproducible.
+node_modules
+dist
+dev-dist
+
+# Env files are NOT copied into the image — the URLs are passed as build args.
+# Copying them would bake whichever environment happened to be checked out.
+.env
+.env.*
+!.env.example
+
+.git
+.github
+.forgejo
+*.log
+.DS_Store

package/templates/react-app/files/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/react-app/files/.env.example

@@ -0,0 +1,34 @@
+# Copy to .env. Vite only exposes variables prefixed VITE_, and inlines them at
+# build time — never put a secret here, it ships to the browser.
+
+# Backend base URL. Better Auth lives at ${VITE_APP_API_URL}/auth.
+VITE_APP_API_URL='http://localhost:5000'
+
+# Dev server port.
+PORT='3000'
+
+# Comma-separated hostnames the dev server will answer to, beyond localhost.
+# Needed when you reach the dev server through a tunnel or a wildcard DNS name.
+VITE_APP_ALLOWED_HOSTS=''
+
+# @feature:start marketing
+# The canonical public origin — the ONE origin that may be indexed. Must match
+# PRODUCTION_ORIGIN in src/features/seo/routes.ts. Anything else (previews,
+# staging, unset) is treated as non-production: the build then emits `noindex`
+# and a disallowing robots.txt, so a preview cannot outrank production.
+VITE_APP_SITE_URL=''
+
+# Published in /.well-known/security.txt. Leave empty and the file is not
+# emitted at all — a security contact pointing at an unmonitored mailbox is
+# worse than none.
+VITE_APP_SUPPORT_EMAIL=''
+# @feature:end
+
+# @feature:start types
+# Credentials for the backend's OpenAPI document, used by `yarn gen` only.
+# Not VITE_-prefixed on purpose: these are read by a Node script, and prefixing
+# them would inline them into the browser bundle.
+API_DOC_URL='http://localhost:5000/openapi-json'
+API_DOC_USER=''
+API_DOC_PASSWORD=''
+# @feature:end

package/templates/react-app/files/.forgejo/workflows/build-and-push.yml

@@ -0,0 +1,55 @@
+# Builds and pushes the app image.
+#
+# Vite compiles the VITE_* URLs into the bundle at build time, so this image is
+# specific to one environment — see the note at the top of the Dockerfile.
+
+name: Build and Push
+
+on:
+  push:
+    branches:
+      - main
+  # Day-to-day work happens on `development`; this lets a build be cut without
+  # merging to main first.
+  workflow_dispatch:
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Generate image tag
+        id: tag
+        run: |
+          DATE=$(date +'%y_%m_%d')
+          RAND=$(printf '%05d' "$((RANDOM % 100000))")
+          echo "TAG=${DATE}_${RAND}" >> "$GITHUB_OUTPUT"
+          echo "OWNER=$(echo '${{ github.repository }}' | cut -d/ -f1)" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ secrets.REGISTRY_URL }}
+          username: ${{ secrets.DK_USER }}
+          password: ${{ secrets.DK_ACCESS_TOKEN }}
+
+      - name: Build and Push
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          context: .
+          build-args: |
+            VITE_APP_API_URL=${{ secrets.VITE_APP_API_URL }}
+            VITE_APP_SITE_URL=${{ secrets.VITE_APP_SITE_URL }}
+            VITE_APP_SUPPORT_EMAIL=${{ secrets.VITE_APP_SUPPORT_EMAIL }}
+          tags: |
+            ${{ secrets.REGISTRY }}/${{ steps.tag.outputs.OWNER }}/web:latest
+            ${{ secrets.REGISTRY }}/${{ steps.tag.outputs.OWNER }}/web:${{ steps.tag.outputs.TAG }}
+
+      - name: Summary
+        run: echo "Pushed web:${{ steps.tag.outputs.TAG }}" >> "$GITHUB_STEP_SUMMARY"

package/templates/react-app/files/.forgejo/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "**"
+      - "!main"
+      - "!development"
+  pull_request:
+
+jobs:
+  verify:
+    name: Lint, typecheck, build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Format check
+        run: yarn format:check
+
+      - name: Lint
+        run: yarn lint
+
+      # `build` typechecks first, so this covers both.
+      - name: Typecheck and build
+        run: yarn build

package/templates/react-app/files/.husky/pre-commit

@@ -0,0 +1 @@
+yarn lint-staged

package/templates/react-app/files/.nvmrc

@@ -0,0 +1 @@
+24.13.0

package/templates/react-app/files/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+dev-dist
+yarn.lock
+# generated API types are formatted by their own pipeline
+src/shared/types/api

package/templates/react-app/files/.prettierrc

@@ -0,0 +1,9 @@
+{
+	"singleQuote": true,
+	"bracketSpacing": true,
+	"useTabs": true,
+	"tabWidth": 2,
+	"printWidth": 120,
+	"semi": true,
+	"trailingComma": "none"
+}

package/templates/react-app/files/.yarnrc.yml

@@ -0,0 +1,2 @@
+nodeLinker: node-modules
+enableTelemetry: false