@aurostack/stacks 0.1.0

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

@@ -0,0 +1,136 @@
+# Static host for a built Vite SPA. One config serves every app in the repo —
+# the Dockerfile copies it into whichever image it is building.
+#
+# 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 in the images that don't.
+	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 — and it has to differ per app, so it is decided
+	# by what the image actually contains rather than by a second config file the
+	# cache rules above would have to be duplicated into.
+	#
+	# A prerendered marketing site should emit `404.html` and answer 404. Without
+	# one it falls through to `index.html`, and if that is a fully prerendered
+	# homepage then every typo'd or stale URL returns 200 with a complete copy of
+	# `/` that canonicalises to `/`. A soft 404 with a body is worse than one
+	# without: there is something for a crawler to index.
+	#
+	# A pure SPA ships no `404.html` and keeps the index.html fallback. Every route
+	# it owns is resolved client-side, so answering 404 would break the app rather
+	# than describe it.
+	#
+	# `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-monorepo/files/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "acme-frontend",
+	"private": true,
+	"version": "0.0.0",
+	"packageManager": "yarn@4.5.3",
+	"engines": {
+		"node": ">=24"
+	},
+	"workspaces": [
+		"apps/*",
+		"packages/*"
+	],
+	"scripts": {
+		"build": "turbo run build",
+		"dev": "turbo run dev",
+		"lint": "turbo run lint",
+		"typecheck": "turbo run typecheck",
+		"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": "turbo run secrets"
+	},
+	"lint-staged": {
+		"*.{ts,tsx,js,jsx,mjs,json,md,css}": "prettier --write"
+	},
+	"devDependencies": {
+		"eslint": "^10.3.0",
+		"husky": "^9.1.7",
+		"lint-staged": "^15.3.0",
+		"prettier": "^3.4.2",
+		"turbo": "^2.5.3",
+		"typescript": "~6.0.2"
+	},
+	"resolutions": {
+		"typescript": "~6.0.2"
+	}
+}

package/templates/react-monorepo/files/packages/api/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from '@acme/config/eslint';
+
+export default config;

package/templates/react-monorepo/files/packages/api/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@acme/api",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@acme/types": "workspace:*",
+		"@reduxjs/toolkit": "^2.12.0",
+		"react-redux": "^9.3.0",
+		"socket.io-client": "^4.8.1"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-dom": ">=19"
+	},
+	"devDependencies": {
+		"@acme/config": "workspace:*",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"react": "^19.2.6",
+		"react-dom": "^19.2.6"
+	}
+}

package/templates/react-monorepo/files/packages/api/src/base-api.ts

@@ -0,0 +1,24 @@
+import { createApi } from '@reduxjs/toolkit/query/react';
+import { baseQueryWithReauth } from './base-query';
+
+/**
+ * The single shared RTK Query API. Feature endpoint slices extend it via
+ * `baseApi.injectEndpoints(...)` (code-split per feature), and realtime socket
+ * events feed cache updates through `baseApi.util.updateQueryData` / `invalidateTags`.
+ */
+export const baseApi = createApi({
+	reducerPath: 'api',
+	baseQuery: baseQueryWithReauth,
+	tagTypes: [
+		// Cache tags, one per resource kind. A query lists what it `provides`, a
+		// mutation lists what it `invalidates`, and RTK Query refetches the
+		// intersection — so these names are the whole invalidation contract.
+		//
+		// One flat namespace shared by every feature slice: two features that both
+		// invent `Items` will invalidate each other's caches, silently. Add yours
+		// here rather than locally, and keep them specific.
+		'CurrentUser',
+		'Sessions'
+	],
+	endpoints: () => ({})
+});

package/templates/react-monorepo/files/packages/api/src/base-query.ts

@@ -0,0 +1,29 @@
+import { fetchBaseQuery, type BaseQueryFn, type FetchArgs, type FetchBaseQueryError } from '@reduxjs/toolkit/query';
+import { getApiBaseUrl, notifyUnauthorized } from './config';
+
+const rawBaseQuery = fetchBaseQuery({
+	baseUrl: '',
+	credentials: 'include'
+});
+
+/**
+ * Shared base query: sends the Better Auth session cookie (credentials:'include'),
+ * prefixes the configured API base URL, and routes 401s to the app's re-auth
+ * handler (registered via configureApi) — the single chokepoint for session expiry.
+ */
+export const baseQueryWithReauth: BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError> = async (
+	args,
+	api,
+	extraOptions
+) => {
+	const base = getApiBaseUrl();
+	const withBase = typeof args === 'string' ? `${base}${args}` : { ...args, url: `${base}${args.url}` };
+
+	const result = await rawBaseQuery(withBase, api, extraOptions);
+
+	if (result.error && result.error.status === 401) {
+		notifyUnauthorized();
+	}
+
+	return result;
+};

package/templates/react-monorepo/files/packages/api/src/config.ts

@@ -0,0 +1,21 @@
+// Runtime configuration for @acme/api. The consuming app calls configureApi()
+// once at startup (before creating the store or issuing requests) to inject the
+// backend base URL and the 401 -> re-auth redirect handler (from @acme/auth).
+
+let apiBaseUrl = '';
+let onUnauthorized: () => void = () => {};
+
+export function configureApi(options: { baseUrl: string; onUnauthorized?: () => void }): void {
+	apiBaseUrl = options.baseUrl.replace(/\/$/, '');
+	if (options.onUnauthorized) {
+		onUnauthorized = options.onUnauthorized;
+	}
+}
+
+export function getApiBaseUrl(): string {
+	return apiBaseUrl;
+}
+
+export function notifyUnauthorized(): void {
+	onUnauthorized();
+}

package/templates/react-monorepo/files/packages/api/src/index.ts

@@ -0,0 +1,15 @@
+// @acme/api — shared Redux store + RTK Query base + Socket.IO client.
+export { baseApi } from './base-api';
+export { baseQueryWithReauth } from './base-query';
+export { uploadBaseQuery } from './upload-query';
+export type { UploadArgs } from './upload-query';
+export { configureApi, getApiBaseUrl, notifyUnauthorized } from './config';
+export { makeStore } from './store';
+export type { AppStore } from './store';
+// @feature:start realtime
+export { connectSocket, getSocket, disconnectSocket, joinRoom, leaveRoom } from './socket';
+export { ServerEvent, ClientEvent, FEED_ROOM, channelRoom } from './realtime-events';
+// @feature:end
+
+// Convenience re-exports so apps get their Redux bindings from one place.
+export { Provider, useDispatch, useSelector, useStore } from 'react-redux';

package/templates/react-monorepo/files/packages/api/src/realtime-events.ts

@@ -0,0 +1,34 @@
+/**
+ * Frontend mirror of the backend realtime wire contract
+ * (backend: `src/realtime/constants`). Keep these names in lockstep with the
+ * server — they are the single source of truth for what the socket speaks, and
+ * a rename on one side that is not mirrored on the other fails silently: the
+ * listener simply never fires.
+ */
+
+/** Server → client event names. */
+export const ServerEvent = {
+	/** Presence roster changed. */
+	PRESENCE_UPDATE: 'presence:update',
+	/** Someone started/stopped typing in a room. */
+	TYPING: 'activity:typing',
+	/** Someone is viewing a resource. */
+	VIEWING: 'activity:viewing',
+	/** A user-directed notification. Scoped to `user:<id>`. */
+	NOTIFICATION: 'notification',
+	/** Something in a channel changed; payload is app-defined. */
+	CHANNEL_UPDATE: 'channel:update'
+} as const;
+
+/** Client → server event names. */
+export const ClientEvent = {
+	JOIN_ROOM: 'room:join',
+	LEAVE_ROOM: 'room:leave',
+	TYPING: 'activity:typing',
+	VIEWING: 'activity:viewing'
+} as const;
+
+/** Firehose room — members see every broadcast on the default channel. */
+export const FEED_ROOM = 'feed';
+/** Room scoped to a single resource. */
+export const channelRoom = (channelId: string) => `channel:${channelId}`;

package/templates/react-monorepo/files/packages/api/src/socket.ts

@@ -0,0 +1,41 @@
+import { io, type Socket } from 'socket.io-client';
+import { ClientEvent } from './realtime-events';
+
+let socket: Socket | null = null;
+
+/**
+ * Connect the realtime Socket.IO client. The Better Auth session cookie is
+ * carried on the handshake via withCredentials. Feature event wiring + the RTK
+ * Query cache bridge land in Phase 2+.
+ */
+export function connectSocket(url: string): Socket {
+	if (socket) {
+		if (!socket.connected) socket.connect();
+		return socket;
+	}
+	socket = io(url, {
+		withCredentials: true,
+		path: '/realtime',
+		autoConnect: true
+	});
+	return socket;
+}
+
+export function getSocket(): Socket | null {
+	return socket;
+}
+
+/** Join a server-side room (forum feed / thread). No-op until connected. */
+export function joinRoom(room: string): void {
+	socket?.emit(ClientEvent.JOIN_ROOM, { room });
+}
+
+/** Leave a previously joined room. */
+export function leaveRoom(room: string): void {
+	socket?.emit(ClientEvent.LEAVE_ROOM, { room });
+}
+
+export function disconnectSocket(): void {
+	socket?.disconnect();
+	socket = null;
+}

package/templates/react-monorepo/files/packages/api/src/store.ts

@@ -0,0 +1,39 @@
+import { configureStore, type Middleware, type Reducer } from '@reduxjs/toolkit';
+import { setupListeners } from '@reduxjs/toolkit/query';
+import { baseApi } from './base-api';
+
+type MakeStoreOptions = {
+	/** App-specific slice reducers (e.g. authSlice, feature UI slices). */
+	reducer?: Record<string, Reducer>;
+	/** Extra middleware (e.g. the socket middleware). */
+	middleware?: Middleware[];
+};
+
+/**
+ * Create an app store wired with the shared RTK Query API + any app slices.
+ * Each app derives its own typed hooks from the returned store, e.g.:
+ *   export const useAppDispatch = useDispatch.withTypes<typeof store.dispatch>();
+ *   export const useAppSelector = useSelector.withTypes<ReturnType<typeof store.getState>>();
+ */
+export function makeStore(options: MakeStoreOptions = {}) {
+	const store = configureStore({
+		reducer: {
+			[baseApi.reducerPath]: baseApi.reducer,
+			...options.reducer
+		},
+		middleware: (getDefaultMiddleware) =>
+			getDefaultMiddleware({
+				serializableCheck: {
+					// Upload endpoints (see `uploadBaseQuery`) carry a FormData body and an
+					// `onProgress` callback in their args. Neither is serializable, and
+					// neither is ever persisted or replayed — only read once, in flight.
+					ignoredActionPaths: ['meta.arg.originalArgs.body', 'meta.arg.originalArgs.onProgress']
+				}
+			}).concat(baseApi.middleware, ...(options.middleware ?? []))
+	});
+
+	setupListeners(store.dispatch);
+	return store;
+}
+
+export type AppStore = ReturnType<typeof makeStore>;

package/templates/react-monorepo/files/packages/api/src/upload-query.ts

@@ -0,0 +1,115 @@
+import type { BaseQueryFn, FetchBaseQueryError } from '@reduxjs/toolkit/query';
+import { getApiBaseUrl, notifyUnauthorized } from './config';
+
+/** How long an upload may stall (no bytes acknowledged) before we give up. */
+const DEFAULT_STALL_TIMEOUT_MS = 45_000;
+
+export type UploadArgs = {
+	url: string;
+	body: FormData;
+	method?: 'POST' | 'PUT' | 'PATCH';
+	/** Called with 0-100 as the request body is written to the socket. */
+	onProgress?: (percent: number) => void;
+	/**
+	 * Abort if no upload progress is observed for this many ms. Guards against a
+	 * connection that opens, stalls mid-body and never errors on its own — the
+	 * common failure on slow mobile uplinks.
+	 */
+	stallTimeoutMs?: number;
+};
+
+/** RTK Query's own marker for an aborted-by-timeout request. */
+const TIMEOUT_ERROR: FetchBaseQueryError = {
+	status: 'TIMEOUT_ERROR',
+	error: 'The upload stalled. Check your connection and try again.'
+};
+
+function parseBody(xhr: XMLHttpRequest): unknown {
+	const text = xhr.responseText;
+	if (!text) return undefined;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+
+/**
+ * Multipart uploads over XMLHttpRequest instead of `fetch`.
+ *
+ * `fetchBaseQuery` cannot report request-body progress (the Fetch API exposes no
+ * upload stream events), so a large file on a slow connection is indistinguishable
+ * from a hung request — the UI can only show an indefinite spinner. XHR still
+ * emits `upload.onprogress`, which lets callers render real progress and lets us
+ * abort a stalled transfer rather than waiting on the OS socket timeout.
+ *
+ * Mirrors `baseQueryWithReauth`: prefixes the configured API base URL, sends the
+ * session cookie, and routes 401s to the shared re-auth handler.
+ */
+export const uploadBaseQuery: BaseQueryFn<UploadArgs, unknown, FetchBaseQueryError> = (args) =>
+	new Promise((resolve) => {
+		const { url, body, method = 'POST', onProgress, stallTimeoutMs = DEFAULT_STALL_TIMEOUT_MS } = args;
+		const xhr = new XMLHttpRequest();
+
+		let stallTimer: ReturnType<typeof setTimeout> | undefined;
+		let settled = false;
+
+		const cleanup = () => {
+			if (stallTimer) clearTimeout(stallTimer);
+		};
+
+		const settle = (result: { data: unknown } | { error: FetchBaseQueryError }) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(result);
+		};
+
+		// Restarted on every progress event; only fires when the socket goes quiet.
+		const armStallTimer = () => {
+			if (stallTimer) clearTimeout(stallTimer);
+			stallTimer = setTimeout(() => {
+				xhr.abort();
+				settle({ error: TIMEOUT_ERROR });
+			}, stallTimeoutMs);
+		};
+
+		xhr.open(method, `${getApiBaseUrl()}${url}`, true);
+		// Matches fetchBaseQuery's `credentials: 'include'` — Better Auth session cookie.
+		xhr.withCredentials = true;
+
+		xhr.upload.onprogress = (event) => {
+			armStallTimer();
+			if (!event.lengthComputable || !onProgress) return;
+			onProgress(Math.round((event.loaded / event.total) * 100));
+		};
+
+		// Body is fully written; the server is now working. Keep the stall guard
+		// running so a server that accepts the bytes and then hangs still fails.
+		xhr.upload.onload = () => {
+			onProgress?.(100);
+			armStallTimer();
+		};
+
+		xhr.onload = () => {
+			const data = parseBody(xhr);
+			if (xhr.status >= 200 && xhr.status < 300) {
+				settle({ data });
+				return;
+			}
+			if (xhr.status === 401) notifyUnauthorized();
+			settle({ error: { status: xhr.status, data } as FetchBaseQueryError });
+		};
+
+		xhr.onerror = () => {
+			settle({
+				error: { status: 'FETCH_ERROR', error: 'The upload failed. Check your connection and try again.' }
+			});
+		};
+
+		// Fires when the transfer is cut mid-body — the truncated-upload case.
+		xhr.onabort = () => settle({ error: TIMEOUT_ERROR });
+
+		armStallTimer();
+		xhr.send(body);
+	});

package/templates/react-monorepo/files/packages/api/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "@acme/config/tsconfig/react.json",
+	"include": ["src"]
+}

package/templates/react-monorepo/files/packages/auth/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from '@acme/config/eslint';
+
+export default config;

package/templates/react-monorepo/files/packages/auth/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@acme/auth",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"better-auth": "^1.6.2"
+	},
+	"peerDependencies": {
+		"@reduxjs/toolkit": "^2",
+		"react": ">=19",
+		"react-dom": ">=19",
+		"react-redux": "^9",
+		"react-router": ">=7"
+	},
+	"devDependencies": {
+		"@acme/config": "workspace:*",
+		"@reduxjs/toolkit": "^2.12.0",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"react": "^19.2.6",
+		"react-dom": "^19.2.6",
+		"react-redux": "^9.3.0",
+		"react-router": "^8.2.0"
+	}
+}

package/templates/react-monorepo/files/packages/auth/src/client.ts

@@ -0,0 +1,27 @@
+import { createAuthClient } from 'better-auth/react';
+import { adminClient } from 'better-auth/client/plugins';
+
+function makeClient(baseURL: string) {
+	// The admin plugin adds `authClient.admin.*` (list/ban/unban/setRole). The
+	// methods are always present but the backend enforces the caller's role, so
+	// including them here is harmless for non-admin apps.
+	return createAuthClient({ baseURL, plugins: [adminClient()] });
+}
+
+let client: ReturnType<typeof makeClient> | null = null;
+
+/** Initialize the Better Auth client singleton (idempotent). */
+export function initAuthClient(baseURL: string) {
+	client ??= makeClient(baseURL);
+	return client;
+}
+
+/** The Better Auth client. Throws if not initialized (call configureAuth first). */
+export function getAuthClient() {
+	if (!client) {
+		throw new Error('Auth client not initialized. Call configureAuth({ authApiBaseUrl, ... }) at app startup.');
+	}
+	return client;
+}
+
+export type AuthClient = ReturnType<typeof makeClient>;

package/templates/react-monorepo/files/packages/auth/src/config.ts

@@ -0,0 +1,22 @@
+import { initAuthClient } from './client';
+import { configureRedirects } from './redirect';
+
+/**
+ * One-shot auth wiring, called by each app at startup (before rendering).
+ *   - authApiBaseUrl: the backend Better Auth base URL (e.g. https://api…/api/auth)
+ *   - authAppUrl: the Auth app origin unauthenticated users are sent to
+ *   - trustedOrigins: origins allowed as post-login redirect targets
+ */
+export function configureAuth(options: {
+	authApiBaseUrl: string;
+	authAppUrl: string;
+	trustedOrigins: string[];
+	defaultRedirect?: string;
+}): void {
+	initAuthClient(options.authApiBaseUrl);
+	configureRedirects({
+		authAppUrl: options.authAppUrl,
+		trustedOrigins: options.trustedOrigins,
+		defaultRedirect: options.defaultRedirect
+	});
+}