@aurostack/stacks 0.1.0

package/templates/react-app/files/Dockerfile

@@ -0,0 +1,52 @@
+# Static build of the app, served by nginx.
+#
+#   docker build --build-arg VITE_APP_API_URL=https://api.example.com -t app .
+#
+# IMPORTANT: Vite inlines `VITE_*` values into the JS bundle at BUILD time, so a
+# built image is pinned to one environment. These are build args, not runtime
+# env — setting them in compose does nothing. Build one image per environment,
+# or move to runtime config.
+
+# ---------- deps ----------
+# Manifests only, so `yarn install` re-runs solely when a dependency changes.
+FROM node:24-alpine AS deps
+WORKDIR /app
+
+COPY package.json yarn.lock .yarnrc.yml ./
+RUN corepack enable && yarn install --immutable
+
+# ---------- build ----------
+FROM node:24-alpine AS build
+WORKDIR /app
+ENV NODE_ENV=production
+# Each stage is a fresh image, so corepack has to be enabled again here —
+# without it `yarn` is the bundled 1.x and refuses the packageManager field.
+RUN corepack enable
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Build args become env vars so Vite's define step picks them up. Process env
+# takes precedence over a committed .env, so a stale checked-in .env cannot leak
+# into the image as long as the arg is supplied.
+ARG VITE_APP_API_URL
+ARG VITE_APP_SITE_URL
+ARG VITE_APP_SUPPORT_EMAIL
+ENV VITE_APP_API_URL=$VITE_APP_API_URL \
+	VITE_APP_SITE_URL=$VITE_APP_SITE_URL \
+	VITE_APP_SUPPORT_EMAIL=$VITE_APP_SUPPORT_EMAIL
+
+# Fail loudly rather than silently producing a bundle with `undefined` URLs baked
+# in — that failure is invisible until the app 404s at runtime.
+RUN test -n "$VITE_APP_API_URL" || (echo "ERROR: --build-arg VITE_APP_API_URL is required" && exit 1)
+
+RUN yarn build
+
+# ---------- runtime ----------
+FROM nginx:stable-alpine AS runtime
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+
+EXPOSE 80
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
+	CMD wget -qO- http://127.0.0.1/healthz || exit 1

package/templates/react-app/files/_gitignore

@@ -0,0 +1,33 @@
+# dependencies
+node_modules/
+
+# yarn (berry, node-modules linker)
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+.pnp.*
+yarn-error.log
+
+# build output
+dist/
+dev-dist/
+*.tsbuildinfo
+
+# env
+.env
+.env.local
+.env.*.local
+.env.test
+.env.production
+
+# editor / os
+.DS_Store
+*.log
+
+# generated OpenAPI schema dump. The types generated FROM it are committed —
+# they are the contract this app compiles against — but the dump itself is a
+# build artefact of whatever backend happened to be running.
+openapi.json

package/templates/react-app/files/build.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+# Build + push the app image.
+#
+#   ./build.sh [env] [tag]
+#
+#   ./build.sh              # uses .env            -> :latest
+#   ./build.sh prod         # uses .env.production
+#   ./build.sh prod 26_07_26_1
+#
+# The VITE_* URLs are compiled INTO the bundle, so the image is specific to the
+# environment it was built for. That is why the env name is an argument: the same
+# image cannot be promoted from staging to prod. Pull the env file first with
+#   yarn secrets -e <env>
+set -eu
+
+ENV_NAME="${1:-dev}"
+TAG="${2:-latest}"
+REGISTRY="${REGISTRY:-registry.example.com/acme}"
+IMAGE="${IMAGE:-web}"
+PLATFORMS="${PLATFORMS:-linux/amd64,linux/arm64}"
+
+case "$ENV_NAME" in
+	dev) ENV_FILE=".env" ;;
+	test) ENV_FILE=".env.test" ;;
+	staging) ENV_FILE=".env.staging" ;;
+	prod | production) ENV_FILE=".env.production" ;;
+	*) echo "unknown env '$ENV_NAME' (dev|test|staging|prod)" >&2; exit 1 ;;
+esac
+
+[ -f "$ENV_FILE" ] || {
+	echo "missing $ENV_FILE — run: yarn secrets -e $ENV_NAME" >&2
+	exit 1
+}
+
+# Read a var out of the env file, tolerating the quoted style these files use.
+read_var() {
+	sed -n "s/^$1=['\"]\{0,1\}\([^'\"]*\)['\"]\{0,1\}$/\1/p" "$ENV_FILE" | tail -1
+}
+
+BUILD_ARGS=""
+for VAR in VITE_APP_API_URL VITE_APP_SITE_URL VITE_APP_SUPPORT_EMAIL; do
+	VALUE="$(read_var "$VAR")"
+	[ -n "$VALUE" ] && BUILD_ARGS="$BUILD_ARGS --build-arg $VAR=$VALUE"
+done
+
+echo "Building for '$ENV_NAME' -> $REGISTRY/$IMAGE:$TAG"
+echo "  (URLs baked in from $ENV_FILE)"
+
+# shellcheck disable=SC2086
+docker buildx build --push --platform "$PLATFORMS" \
+	$BUILD_ARGS \
+	-t "$REGISTRY/$IMAGE:$TAG" \
+	.

package/templates/react-app/files/docker/nginx.conf

@@ -0,0 +1,134 @@
+# Static host for the built Vite SPA.
+#
+# The cache rules are load-bearing, not cosmetic: get them wrong and returning
+# users are pinned to a stale build. Rule of thumb — anything with a content
+# hash in its name is immutable forever; anything with a stable name must be
+# revalidated every time.
+
+server {
+	listen 80;
+	server_name _;
+	root /usr/share/nginx/html;
+	index index.html;
+
+	# Compose/orchestrator health probe. Must not be logged or it floods access.log.
+	location = /healthz {
+		access_log off;
+		add_header Content-Type text/plain;
+		return 200 "ok\n";
+	}
+
+	gzip on;
+	gzip_vary on;
+	gzip_min_length 1024;
+	gzip_proxied any;
+	gzip_types text/plain text/css application/javascript application/json
+	           image/svg+xml application/manifest+json;
+
+	# Vite emits content-hashed filenames here, so the content can never change
+	# under a given URL — safe to cache for a year.
+	# NB: no `expires` directive. `expires` emits its own Cache-Control, so
+	# combining it with add_header sends the header twice and clients disagree on
+	# which wins — `immutable` can be dropped. One explicit header instead.
+	location /assets/ {
+		add_header Cache-Control "public, max-age=31536000, immutable" always;
+		try_files $uri =404;
+	}
+
+	# The service worker and its Workbox runtime keep STABLE names across builds.
+	# If these are cached the browser keeps running the old worker, which keeps
+	# serving the old precached app shell — users get stuck on a previous version
+	# with no way out but a hard reload. Only a PWA build ships them; the rule is
+	# harmless otherwise.
+	location ~* ^/(sw\.js|registerSW\.js|workbox-[^/]+\.js)$ {
+		add_header Cache-Control "no-cache, must-revalidate" always;
+		expires off;
+		try_files $uri =404;
+	}
+
+	# Re-checked on every load so a deploy is picked up immediately, and so the
+	# manifest's start_url/icons stay in step with the installed PWA.
+	location ~* ^/(manifest\.webmanifest|manifest\.json)$ {
+		add_header Cache-Control "no-cache, must-revalidate" always;
+		expires off;
+		try_files $uri =404;
+	}
+
+	# Long-lived but not immutable: stable names, so they must stay revalidatable,
+	# but they rarely change.
+	location ~* \.(png|jpg|jpeg|gif|svg|ico|webp|woff2?)$ {
+		add_header Cache-Control "public, max-age=604800" always;
+		try_files $uri =404;
+	}
+
+	# SPA fallback. index.html is never cached — it references the hashed bundles,
+	# so a cached copy would keep pointing at assets from the previous deploy.
+	#
+	# `$uri/index.html` comes BEFORE `$uri/` deliberately. If you add a prerender
+	# pass that emits `about/index.html`, matching `$uri/` on a directory makes
+	# nginx 301 to the trailing-slash form — verified: `/about` redirected to
+	# `/about/`. That fights the canonical tag and the sitemap, which both use the
+	# slashless `/about`, and adds a hop for every crawler. Serving the file
+	# directly returns 200 at the canonical URL. Harmless for a pure SPA: it ships
+	# no such directories, so the extra probe never matches.
+	location / {
+		try_files $uri $uri/index.html $uri/ @fallback;
+		add_header Cache-Control "no-cache, must-revalidate" always;
+		expires off;
+	}
+
+	# What an unknown path gets, decided by what the build actually emitted rather
+	# than by a config flag that can disagree with it.
+	#
+	# A pure SPA ships no `404.html`, so this falls through to `index.html` and the
+	# router renders its own not-found page. Answering a real 404 here instead
+	# would break every client-side route.
+	#
+	# If you add a prerender pass, emit `404.html` and this starts answering 404
+	# automatically. That matters: without one, a prerendered homepage means every
+	# typo'd or stale URL returns 200 with a full copy of `/`, and a soft 404 with
+	# a body is worse than one without — there is something for a crawler to
+	# index.
+	#
+	# `if` is limited here to `return` and `rewrite ... last`, the two directives
+	# documented as safe inside a location.
+	location @fallback {
+		error_page 404 /404.html;
+		if (-f $document_root/404.html) {
+			return 404;
+		}
+		rewrite ^ /index.html last;
+	}
+
+	# Reachable only through error_page, so the page cannot also be served as a
+	# regular 200 at /404.html and be indexed on its own.
+	location = /404.html {
+		internal;
+		add_header Cache-Control "no-cache, must-revalidate" always;
+		expires off;
+	}
+
+	# Modest hardening. Deliberately NO Content-Security-Policy header: the apps
+	# ship an inline <script> in index.html that applies the saved theme before
+	# first paint, and a default CSP without 'unsafe-inline' would block it and
+	# reintroduce the light-mode flash. Add CSP only with a nonce/hash for that
+	# script. HSTS belongs on the TLS-terminating proxy in front of this, not here.
+	add_header X-Content-Type-Options "nosniff" always;
+	add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+	add_header X-Frame-Options "SAMEORIGIN" always;
+
+	# RFC 9116 puts security.txt under /.well-known/, which the deny below would
+	# otherwise 403 — that is the whole point of this block. `^~` is what makes the
+	# exception stick: it tells nginx that once this prefix matches, regex
+	# locations are skipped entirely, so `location ~ /\.` never gets a look at it.
+	# Deliberately adds no headers of its own, because `add_header` in a location
+	# REPLACES the inherited set rather than extending it — the server-level
+	# hardening headers above would silently stop applying here.
+	location ^~ /.well-known/ {
+		try_files $uri =404;
+	}
+
+	location ~ /\. {
+		deny all;
+	}
+}

package/templates/react-app/files/eslint.config.mjs

@@ -0,0 +1,75 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+
+/**
+ * Flat ESLint config for a React 19 + TypeScript app.
+ */
+export default tseslint.config(
+	// `dev-dist` is vite-plugin-pwa's dev output (Workbox sources). Generated and
+	// gitignored — linting it only produces "rule not found" noise that makes
+	// `yarn lint` fail permanently, hiding real findings. `src/shared/types/api`
+	// is generated from the OpenAPI schema and formatted by its own pipeline.
+	{ ignores: ['dist', 'dev-dist', 'node_modules', 'src/shared/types/api'] },
+	{
+		files: ['**/*.{ts,tsx}'],
+		extends: [
+			js.configs.recommended,
+			tseslint.configs.recommended,
+			reactHooks.configs.flat.recommended,
+			reactRefresh.configs.vite
+		],
+		languageOptions: {
+			ecmaVersion: 2023,
+			globals: globals.browser
+		},
+		rules: {
+			'@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+			'@typescript-eslint/no-empty-object-type': 'off',
+
+			// The shadcn primitives export their cva variants next to the component
+			// (`buttonVariants`), which is what `allowConstantExport` exists for.
+			// Left as a warning rather than an error: a fast-refresh hint should not
+			// be able to fail CI on a file that works.
+			'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+
+			// iOS auto-zooms a focused text control whose font-size is under 16px and
+			// never restores the zoom on blur, so one tap leaves the user zoomed for
+			// the session — in the installed PWA too. `text-sm` is 14px.
+			//
+			// The lookbehind lets `sm:text-sm` through: `text-base sm:text-sm` is the
+			// correct fix (16px on mobile, the intended density from `sm` up).
+			//
+			// Only catches literal className strings on raw `<input>`/`<textarea>`/
+			// `<select>` — that is exactly how this regresses. Prefer `SearchInput` /
+			// `Input` from `@/shared/ui`, which already handle it.
+			'no-restricted-syntax': [
+				'error',
+				{
+					selector:
+						"JSXOpeningElement[name.name=/^(input|textarea|select)$/] JSXAttribute[name.name='className'] Literal[value=/(?<![:-])(text-xs|text-sm)(?![a-zA-Z0-9-])/]",
+					message:
+						'A text input under 16px makes iOS zoom in on focus and never zoom back out. Use `text-base sm:text-sm`, or the SearchInput / Input components from @/shared/ui.'
+				}
+			]
+		}
+	},
+	{
+		// `router.tsx` exports the router object alongside the shell components it
+		// mounts. Splitting them would mean a second file existing only to satisfy a
+		// heuristic — the router is not a component and is never hot-swapped.
+		files: ['**/app/router.tsx'],
+		rules: { 'react-refresh/only-export-components': 'off' }
+	},
+	{
+		// The shadcn primitives export their cva variants beside the component
+		// (`buttonVariants`, `alertVariants`) — that is how the upstream components
+		// are written, and it is why consumers can compose them. `allowConstantExport`
+		// does not cover a `cva()` call, so without this the rule warns permanently on
+		// unmodified upstream code, which is how a lint report stops being read.
+		files: ['**/components/ui/**'],
+		rules: { 'react-refresh/only-export-components': 'off' }
+	}
+);

package/templates/react-app/files/index.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+		<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
+		<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
+		<link rel="icon" href="/favicon.ico" sizes="any" />
+		<link rel="manifest" href="/site.webmanifest" />
+		<meta name="theme-color" content="%THEME_LIGHT%" />
+		<!--
+			Applies the saved (or system) theme before first paint, so the app never
+			flashes light then flips to dark. Mirrors `themeInitScript` in
+			src/shared/ui — inlined because it must run before any module loads. Keep
+			the two in sync. %THEME_LIGHT/DARK% come from THEME_COLORS via vite.config.
+		-->
+		<script>
+			(function () {
+				try {
+					var m = localStorage.getItem('acme-theme');
+					var d =
+						m === 'dark' || ((m === null || m === 'system') && matchMedia('(prefers-color-scheme: dark)').matches);
+					var r = document.documentElement;
+					r.classList.toggle('dark', d);
+					r.style.colorScheme = d ? 'dark' : 'light';
+					var t = document.querySelector('meta[name="theme-color"]');
+					if (t) t.setAttribute('content', d ? '%THEME_DARK%' : '%THEME_LIGHT%');
+				} catch (e) {}
+			})();
+		</script>
+		<!--
+			globals.css only styles `body`, so without this the UA canvas paints white
+			for the moment before the stylesheet lands — a white flash on a dark load.
+		-->
+		<style>
+			html {
+				background: %THEME_LIGHT%;
+			}
+			html.dark {
+				background: %THEME_DARK%;
+			}
+		</style>
+		<meta name="description" content="Acme Corp." />
+		<!--
+			Every route this app serves is private, so nothing here should be indexed.
+			`robots.txt` only discourages crawling, while `noindex` prevents listing,
+			so both belong in a deployment. This app's routes include password-reset
+			and email-verify URLs.
+
+			With the marketing site included this tag goes away: indexing is then
+			decided per route by `PageMeta`, and the build emits a `noindex` of its own
+			on any non-production origin. See vite.config.ts.
+		-->
+		<meta name="robots" content="noindex, nofollow" /> <!-- @feature !marketing -->
+		<title>%APP_TITLE%</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

package/templates/react-app/files/openapi-ts.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from '@hey-api/openapi-ts';
+
+export default defineConfig({
+	input: 'openapi.json',
+	output: {
+		format: 'prettier',
+		path: 'src/shared/types/api',
+		lint: 'eslint'
+	},
+	exportCore: false,
+	client: '@hey-api/client-fetch',
+	experimentalParser: true,
+	plugins: [
+		{
+			name: 'zod'
+		},
+		{
+			name: '@hey-api/typescript',
+			enums: 'typescript'
+		}
+	]
+});

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

@@ -0,0 +1,80 @@
+{
+	"name": "acme-app",
+	"private": true,
+	"version": "0.0.0",
+	"type": "module",
+	"packageManager": "yarn@4.5.3",
+	"engines": {
+		"node": ">=24"
+	},
+	"scripts": {
+		"dev": "vite",
+		"build": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.node.json && vite build",
+		"preview": "vite preview",
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.node.json",
+		"format": "prettier --write \"**/*.{ts,tsx,js,jsx,mjs,json,md,css}\"",
+		"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,mjs,json,md,css}\"",
+		"prepare": "husky",
+		"secrets": "node .bin/secrets.js",
+		"gen:schema": "node .bin/openapi.js",
+		"gen:types": "openapi-ts",
+		"gen": "node .bin/openapi.js && openapi-ts"
+	},
+	"lint-staged": {
+		"*.{ts,tsx,js,jsx,mjs,json,md,css}": "prettier --write"
+	},
+	"dependencies": {
+		"@fontsource-variable/inter": "^5.3.0",
+		"@radix-ui/react-label": "^2.1.7",
+		"@radix-ui/react-popover": "^1.1.21",
+		"@radix-ui/react-select": "^2.3.4",
+		"@radix-ui/react-slot": "^1.2.5",
+		"@reduxjs/toolkit": "^2.12.0",
+		"apexcharts": "^6.5.0",
+		"better-auth": "^1.6.2",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"date-fns": "^3",
+		"formik": "^2.4.9",
+		"lucide-react": "^1.17.0",
+		"react": "^19.2.6",
+		"react-apexcharts": "^2.1.1",
+		"react-day-picker": "^9",
+		"react-dom": "^19.2.6",
+		"react-redux": "^9.3.0",
+		"react-router": "^8.2.0",
+		"socket.io-client": "^4.8.1",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.6.0",
+		"zod": "^4.4.3",
+		"zod-formik-adapter": "^2.0.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@hey-api/client-fetch": "^0.5.2",
+		"@hey-api/openapi-ts": "^0.59.1",
+		"@tailwindcss/vite": "^4.3.0",
+		"@types/node": "^24.10.1",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.1",
+		"axios": "^1.7.9",
+		"dotenv": "^16.4.7",
+		"eslint": "^10.3.0",
+		"eslint-plugin-react-hooks": "^7.1.1",
+		"eslint-plugin-react-refresh": "^0.5.2",
+		"globals": "^17.6.0",
+		"husky": "^9.1.7",
+		"lint-staged": "^15.3.0",
+		"prettier": "^3.4.2",
+		"tiny-invariant": "^1.3.3",
+		"typescript": "~6.0.2",
+		"typescript-eslint": "^8.59.2",
+		"vite": "^8.0.12",
+		"vite-plugin-pwa": "^1.3.0"
+	},
+	"resolutions": {
+		"typescript": "~6.0.2"
+	}
+}

package/templates/react-app/files/src/app/nav.tsx

@@ -0,0 +1,32 @@
+import { Home, Settings } from 'lucide-react';
+import { ShieldCheck } from 'lucide-react'; // @feature admin
+import type { NavItem } from '@/shared/layouts';
+import { appPath } from '@/lib/paths';
+import { ADMIN_BASE } from '@/lib/paths'; // @feature admin
+
+/**
+ * Drives the app shell's navigation. Keep it in step with `router.tsx` — the
+ * shell derives the sidebar from this list, not from the router, so a route
+ * added in one place and not the other is simply unreachable or dead.
+ *
+ * Paths come from `appPath` rather than being written out, because the app's
+ * mount point moves when the marketing site is included. `icon` is a rendered
+ * element, not a component reference.
+ */
+export const NAV_ITEMS: NavItem[] = [
+	{ to: appPath(), label: 'Home', icon: <Home className="size-4" />, end: true },
+	{ to: appPath('settings'), label: 'Settings', icon: <Settings className="size-4" /> }
+];
+
+// @feature:start admin
+/**
+ * The console's own nav. Separate from `NAV_ITEMS` on purpose: the admin section
+ * is a different branch of the router behind a different guard, and mixing an
+ * admin link into the member sidebar would render it for members too — a link
+ * that 403s is a worse answer than no link.
+ */
+export const ADMIN_NAV_ITEMS: NavItem[] = [
+	{ to: ADMIN_BASE, label: 'Overview', icon: <ShieldCheck className="size-4" />, end: true },
+	{ to: appPath(), label: 'Back to app', icon: <Home className="size-4" /> }
+];
+// @feature:end

package/templates/react-app/files/src/app/providers.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import { Provider } from 'react-redux';
+import { configureApi } from '@/shared/api';
+import { AuthProvider, configureAuth, redirectToLogin } from '@/shared/auth';
+import { MetaProvider, ThemeProvider, Toaster, installZodErrorMap } from '@/shared/ui';
+import { API_URL } from '@/lib/env';
+import { appPath } from '@/lib/paths';
+import { store } from './store';
+
+// Wired at module scope, before anything renders. The first thing this app does
+// is ask the backend who the user is, and doing this in an effect would put that
+// request behind a render pass for no gain.
+configureApi({ baseUrl: API_URL, onUnauthorized: () => redirectToLogin() });
+configureAuth({
+	authApiBaseUrl: `${API_URL}/auth`,
+	// `trustedOrigins` is left to its default of this app's own origin — one
+	// deployment, one origin. Add to it only for a deliberate hand-off elsewhere;
+	// every entry is a URL an attacker may put in `?redirect=`.
+	defaultRedirect: appPath()
+});
+installZodErrorMap();
+
+export function Providers({ children }: { children: ReactNode }) {
+	return (
+		// ThemeProvider above the Redux Provider: it only touches the document
+		// (`dark` class, color-scheme, theme-color meta) and must not re-render
+		// through the store.
+		<ThemeProvider>
+			<MetaProvider>
+				<Provider store={store}>
+					<AuthProvider>
+						{children}
+						<Toaster />
+					</AuthProvider>
+				</Provider>
+			</MetaProvider>
+		</ThemeProvider>
+	);
+}