@aurostack/stacks 0.1.0

package/templates/react-monorepo/files/packages/auth/src/guards.tsx

@@ -0,0 +1,61 @@
+import { type ReactNode, useEffect } from 'react';
+import { Outlet } from 'react-router';
+import { useAuth } from './hooks';
+import { redirectToLogin } from './redirect';
+
+type GuardProps = {
+	children?: ReactNode;
+	/**
+	 * Shown while the session is resolving or a redirect is in flight.
+	 *
+	 * Required on purpose. This used to default to `null`, which meant the app
+	 * rendered *nothing* for the entire cross-origin session round trip — ~880 ms
+	 * measured against the deployed API, and worse on mobile. Pass the shell
+	 * skeleton so the frame is on screen while the session resolves; there is no
+	 * correct case for gating a whole app behind a blank screen.
+	 */
+	fallback: ReactNode;
+};
+
+/** Requires any authenticated session; otherwise redirects to the Auth app. */
+export function ProtectedRoute({ children, fallback }: GuardProps) {
+	const { status } = useAuth();
+
+	useEffect(() => {
+		if (status === 'unauthenticated') redirectToLogin();
+	}, [status]);
+
+	if (status !== 'authenticated') return <>{fallback}</>;
+	return <>{children ?? <Outlet />}</>;
+}
+
+type RoleRouteProps = GuardProps & {
+	/** Roles allowed to view (any match). Compared against session.user.role. */
+	allow: string[];
+	/** Rendered when authenticated but lacking a required role (403). Required for
+	 *  the same reason as `fallback` — a silent blank 403 looks like a broken app. */
+	forbidden: ReactNode;
+};
+
+/**
+ * Requires an authenticated session AND one of `allow` roles.
+ * 401 (no session) -> redirect to Auth; 403 (wrong role) -> forbidden UI.
+ */
+export function RoleRoute({ allow, children, fallback, forbidden }: RoleRouteProps) {
+	const { status, user } = useAuth();
+
+	useEffect(() => {
+		if (status === 'unauthenticated') redirectToLogin();
+	}, [status]);
+
+	if (status !== 'authenticated') return <>{fallback}</>;
+
+	const roles = (user?.role ?? '')
+		.split(',')
+		.map((role) => role.trim())
+		.filter(Boolean);
+	const permitted = allow.some((role) => roles.includes(role));
+	if (!permitted) return <>{forbidden}</>;
+
+	return <>{children ?? <Outlet />}</>;
+}

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

@@ -0,0 +1,13 @@
+import { useSelector } from 'react-redux';
+import { selectAuth } from './slice';
+
+/** Synchronous auth state for rendering/gating. Hydrated from Better Auth. */
+export function useAuth() {
+	const { user, status } = useSelector(selectAuth);
+	return {
+		user,
+		status,
+		isAuthenticated: status === 'authenticated',
+		isLoading: status === 'loading'
+	};
+}

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

@@ -0,0 +1,20 @@
+// @acme/auth — centralized authentication on Better Auth.
+export { configureAuth } from './config';
+export { initAuthClient, getAuthClient } from './client';
+export type { AuthClient } from './client';
+export { AuthProvider } from './provider';
+export { useAuth } from './hooks';
+export { ProtectedRoute, RoleRoute } from './guards';
+export { redirectToLogin, getSafeRedirect, configureRedirects } from './redirect';
+export { signOut, broadcastAuthEvent, AUTH_BROADCAST_CHANNEL } from './logout';
+export {
+	authReducer,
+	sessionLoading,
+	sessionLoaded,
+	sessionCleared,
+	selectAuth,
+	selectAuthUser,
+	selectAuthStatus,
+	selectIsAuthenticated
+} from './slice';
+export type { AuthUser, AuthStatus } from './slice';

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

@@ -0,0 +1,23 @@
+import { getAuthClient } from './client';
+
+export const AUTH_BROADCAST_CHANNEL = 'acme-auth';
+
+/** Notify other tabs/apps of an auth event (e.g. logout) so stale UI can react. */
+export function broadcastAuthEvent(type: 'login' | 'logout'): void {
+	try {
+		const channel = new BroadcastChannel(AUTH_BROADCAST_CHANNEL);
+		channel.postMessage({ type });
+		channel.close();
+	} catch {
+		/* BroadcastChannel unsupported — no-op */
+	}
+}
+
+/** Sign out (clears the shared-domain cookie), broadcast, then optionally redirect. */
+export async function signOut(options?: { redirectTo?: string }): Promise<void> {
+	await getAuthClient().signOut();
+	broadcastAuthEvent('logout');
+	if (options?.redirectTo) {
+		window.location.assign(options.redirectTo);
+	}
+}

package/templates/react-monorepo/files/packages/auth/src/provider.tsx

@@ -0,0 +1,52 @@
+import { type ReactNode, useEffect } from 'react';
+import { useDispatch } from 'react-redux';
+import { getAuthClient } from './client';
+import { sessionCleared, sessionLoaded, sessionLoading, type AuthUser } from './slice';
+import { AUTH_BROADCAST_CHANNEL } from './logout';
+
+function toAuthUser(user: Record<string, unknown> | null | undefined): AuthUser | null {
+	if (!user) return null;
+	return {
+		id: String(user.id),
+		email: String(user.email ?? ''),
+		name: (user.name as string | undefined) ?? null,
+		image: (user.image as string | undefined) ?? null,
+		role: (user.role as string | undefined) ?? null,
+		emailVerified: Boolean(user.emailVerified),
+		onboardingCompletedAt: (user.onboardingCompletedAt as string | undefined) ?? null
+	};
+}
+
+/**
+ * Bootstraps the Better Auth session and hydrates the authSlice. Must render
+ * inside the Redux <Provider>. Guards read the resulting status for gating.
+ * Also syncs logout across tabs via BroadcastChannel.
+ */
+export function AuthProvider({ children }: { children: ReactNode }) {
+	const dispatch = useDispatch();
+	const session = getAuthClient().useSession();
+
+	useEffect(() => {
+		if (session.isPending) {
+			dispatch(sessionLoading());
+			return;
+		}
+		const user = (session.data?.user as Record<string, unknown> | undefined) ?? null;
+		dispatch(sessionLoaded(toAuthUser(user)));
+	}, [session.isPending, session.data, dispatch]);
+
+	useEffect(() => {
+		let channel: BroadcastChannel | null = null;
+		try {
+			channel = new BroadcastChannel(AUTH_BROADCAST_CHANNEL);
+			channel.onmessage = (event: MessageEvent<{ type?: string }>) => {
+				if (event.data?.type === 'logout') dispatch(sessionCleared());
+			};
+		} catch {
+			/* BroadcastChannel unsupported — no-op */
+		}
+		return () => channel?.close();
+	}, [dispatch]);
+
+	return <>{children}</>;
+}

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

@@ -0,0 +1,37 @@
+// Cross-app redirect helpers with open-redirect protection. The Auth app lives
+// on its own origin; Client/Admin send unauthenticated users here and get them
+// back to where they started. Redirect targets are validated against an
+// allowlist so an attacker can't craft ?redirect=https://evil.example.
+
+let authAppUrl = '';
+let trustedOrigins: string[] = [];
+let defaultRedirect = '';
+
+export function configureRedirects(options: {
+	authAppUrl: string;
+	trustedOrigins: string[];
+	defaultRedirect?: string;
+}): void {
+	authAppUrl = options.authAppUrl.replace(/\/$/, '');
+	trustedOrigins = options.trustedOrigins.map((origin) => origin.replace(/\/$/, ''));
+	defaultRedirect = options.defaultRedirect ?? '';
+}
+
+/** Validate a redirect target against the trusted-origin allowlist. */
+export function getSafeRedirect(target: string | null | undefined, fallback: string = defaultRedirect): string {
+	if (!target) return fallback;
+	try {
+		const url = new URL(target, window.location.origin);
+		if (trustedOrigins.includes(url.origin)) return url.toString();
+	} catch {
+		/* not a valid URL — fall through to fallback */
+	}
+	return fallback;
+}
+
+/** Send an unauthenticated user to the Auth app, preserving where they were. */
+export function redirectToLogin(returnTo: string = window.location.href): void {
+	const url = new URL('/login', authAppUrl || window.location.origin);
+	url.searchParams.set('redirect', returnTo);
+	window.location.assign(url.toString());
+}

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

@@ -0,0 +1,54 @@
+import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
+
+export type AuthUser = {
+	id: string;
+	email: string;
+	name?: string | null;
+	image?: string | null;
+	role?: string | null;
+	emailVerified: boolean;
+	/** ISO timestamp set when onboarding is finished/skipped; null = not yet onboarded. */
+	onboardingCompletedAt?: string | null;
+};
+
+export type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+
+type AuthState = {
+	user: AuthUser | null;
+	status: AuthStatus;
+};
+
+const initialState: AuthState = {
+	user: null,
+	status: 'loading'
+};
+
+// Minimal projection of the Better Auth session for synchronous, app-wide reads.
+// Better Auth remains the source of truth; this slice is hydrated FROM it (AuthProvider).
+const authSlice = createSlice({
+	name: 'auth',
+	initialState,
+	reducers: {
+		sessionLoading(state) {
+			state.status = 'loading';
+		},
+		sessionLoaded(state, action: PayloadAction<AuthUser | null>) {
+			state.user = action.payload;
+			state.status = action.payload ? 'authenticated' : 'unauthenticated';
+		},
+		sessionCleared(state) {
+			state.user = null;
+			state.status = 'unauthenticated';
+		}
+	}
+});
+
+export const { sessionLoading, sessionLoaded, sessionCleared } = authSlice.actions;
+export const authReducer = authSlice.reducer;
+
+type WithAuth = { auth: AuthState };
+
+export const selectAuth = (state: WithAuth) => state.auth;
+export const selectAuthUser = (state: WithAuth) => state.auth.user;
+export const selectAuthStatus = (state: WithAuth) => state.auth.status;
+export const selectIsAuthenticated = (state: WithAuth) => state.auth.status === 'authenticated';

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

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

package/templates/react-monorepo/files/packages/config/README.md

@@ -0,0 +1,47 @@
+# @acme/config
+
+Shared tooling for the Acme frontend monorepo. Not a runtime package — it exports config assets other packages/apps extend.
+
+## Exports
+
+| Import                               | What                                                                                             |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `@acme/config/eslint`              | Flat ESLint config (React 19 + TS). Default-export an array.                                     |
+| `@acme/config/tsconfig/base.json`  | Base TS compiler options (strict, bundler, es2023).                                              |
+| `@acme/config/tsconfig/react.json` | Extends base + DOM libs + `react-jsx`. For apps/UI packages.                                     |
+| `@acme/config/tsconfig/node.json`  | Extends base + node types. For `vite.config.ts` / scripts.                                       |
+| `@acme/config/vite`                | `defineAppConfig({ rootDir })` Vite factory (React + Tailwind v4, `@`→`src`, env-driven server). |
+| `@acme/config/tailwind.css`        | Shared Tailwind v4 `@theme` design tokens.                                                       |
+
+## Consumption
+
+**ESLint** (`eslint.config.mjs`):
+
+```js
+import config from '@acme/config/eslint';
+export default config;
+```
+
+**tsconfig** (`tsconfig.json`):
+
+```json
+{
+	"extends": "@acme/config/tsconfig/react.json",
+	"compilerOptions": { "paths": { "@/*": ["./src/*"] } },
+	"include": ["src"]
+}
+```
+
+**Vite** (`vite.config.ts`):
+
+```ts
+import { defineAppConfig } from '@acme/config/vite';
+export default defineAppConfig({ rootDir: import.meta.dirname });
+```
+
+**Tailwind** (`src/index.css`):
+
+```css
+@import 'tailwindcss';
+@import '@acme/config/tailwind.css';
+```

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

@@ -0,0 +1,83 @@
+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';
+
+/**
+ * Shared flat ESLint config for Acme React 19 + TypeScript apps and packages.
+ *
+ * Usage in a consumer's `eslint.config.mjs`:
+ *   import config from '@acme/config/eslint';
+ *   export default config;
+ *
+ * To extend:
+ *   import config from '@acme/config/eslint';
+ *   export default [...config, { rules: { ... } }];
+ */
+export default tseslint.config(
+	// `dev-dist` is vite-plugin-pwa's dev output (Workbox sources). Generated, and
+	// gitignored — linting it only produced "rule not found" noise that made
+	// `yarn lint` fail permanently on the client app, hiding real findings.
+	{ ignores: ['dist', 'dev-dist', 'node_modules', '.turbo', 'src/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 regressed before. Prefer
+			// `SearchInput`/`ComboboxFilter`/`Input` from `@acme/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 / ComboboxFilter / Input components from @acme/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-monorepo/files/packages/config/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@acme/config",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		"./eslint": "./eslint/base.mjs",
+		"./tailwind.css": "./tailwind/theme.css",
+		"./vite": {
+			"types": "./vite/index.d.ts",
+			"default": "./vite/index.mjs"
+		},
+		"./tsconfig/base.json": "./tsconfig/base.json",
+		"./tsconfig/react.json": "./tsconfig/react.json",
+		"./tsconfig/node.json": "./tsconfig/node.json"
+	},
+	"files": [
+		"eslint",
+		"tailwind",
+		"vite",
+		"tsconfig"
+	],
+	"dependencies": {
+		"@eslint/js": "^10.0.1",
+		"@tailwindcss/vite": "^4.3.0",
+		"@vitejs/plugin-react": "^6.0.1",
+		"eslint-plugin-react-hooks": "^7.1.1",
+		"eslint-plugin-react-refresh": "^0.5.2",
+		"globals": "^17.6.0",
+		"typescript-eslint": "^8.59.2"
+	},
+	"peerDependencies": {
+		"eslint": ">=10",
+		"typescript": ">=6",
+		"vite": ">=8"
+	}
+}

package/templates/react-monorepo/files/packages/config/tailwind/theme.css

@@ -0,0 +1,48 @@
+/**
+ * Acme Corp — shared Tailwind v4 brand tokens (Wise-derived design system).
+ * Source of truth: Claude Design "Acme Corp Design System" (colors_and_type.css).
+ *
+ * Consume in an app's main CSS entry (via @acme/ui/globals.css):
+ *   @import 'tailwindcss';
+ *   @import '@acme/config/tailwind.css';
+ *
+ * These are the BRAND tokens (palette shades, ink, semantic, fonts). The shadcn
+ * semantic layer (--background/--foreground/--primary/...) is layered on top by
+ * @acme/ui/globals.css, which owns light/dark theming.
+ *
+ * Brand rule: Wise Green (#9fe870) is the CTA accent ONLY — never a success color.
+ */
+@theme {
+	/* Brand green shades (primary itself is owned by the shadcn layer) */
+	--color-primary-active: #cdffad;
+	--color-primary-neutral: #c5edab;
+	--color-primary-pale: #e2f6d5;
+	--color-on-primary: #0e0f0c;
+
+	/* Surfaces & ink */
+	--color-sage: #e8ebe6;
+	--color-ink: #0e0f0c;
+	--color-ink-deep: #163300;
+	--color-body: #454745;
+	--color-mute: #868685;
+
+	/* Semantic — status only, never the brand green */
+	--color-positive: #2ead4b;
+	--color-positive-deep: #054d28;
+	--color-warning: #ffd11a;
+	--color-warning-deep: #b86700;
+	--color-negative: #d03238;
+	--color-negative-deep: #a72027;
+
+	/* Illustrative accents (inside illustrations only, never UI fills) */
+	--color-accent-orange: #ffc091;
+	--color-accent-cyan: #38c8ff;
+
+	/* Typography — Inter stands in for proprietary Wise Sans */
+	/* 'Manrope' was listed here but never loaded — and sat *after* Inter, so it
+	   could never have been used even if it were. Removed as dead. If the design
+	   really wants Manrope for display type it needs its own @font-face AND to be
+	   ordered ahead of Inter — a deliberate visual change, not a cleanup. */
+	--font-display: 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;
+	--font-sans: 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;
+}

package/templates/react-monorepo/files/packages/config/tsconfig/base.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "Acme base",
+	"compilerOptions": {
+		"target": "es2023",
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"lib": ["ES2023"],
+		"types": [],
+		"skipLibCheck": true,
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"moduleDetection": "force",
+		"isolatedModules": true,
+		"noEmit": true,
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true,
+		"erasableSyntaxOnly": true
+	}
+}

package/templates/react-monorepo/files/packages/config/tsconfig/node.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "Acme Node (build scripts, vite config)",
+	"extends": "./base.json",
+	"compilerOptions": {
+		"lib": ["ES2023"],
+		"types": ["node"]
+	}
+}

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

@@ -0,0 +1,9 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "Acme React (apps + UI libraries)",
+	"extends": "./base.json",
+	"compilerOptions": {
+		"lib": ["ES2023", "DOM", "DOM.Iterable"],
+		"jsx": "react-jsx"
+	}
+}

package/templates/react-monorepo/files/packages/config/vite/index.d.ts

@@ -0,0 +1,18 @@
+import type { PluginOption, UserConfig, UserConfigExport } from 'vite';
+
+export interface DefineAppConfigOptions {
+	/** The app root directory. Pass `import.meta.dirname`. */
+	rootDir: string;
+	/**
+	 * Theme background colours, used to substitute `%THEME_LIGHT%` / `%THEME_DARK%`
+	 * in `index.html`. Pass `THEME_COLORS` from `@acme/ui/theme-colors`; omitting
+	 * it leaves the placeholders in the markup.
+	 */
+	themeColors?: { light: string; dark: string };
+	/** Extra plugins appended after the base React + Tailwind plugins. */
+	plugins?: PluginOption[];
+	/** Optional Vite config overrides merged into the base config. */
+	overrides?: UserConfig;
+}
+
+export function defineAppConfig(options: DefineAppConfigOptions): UserConfigExport;