@aurostack/stacks 0.1.0

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

@@ -0,0 +1,23 @@
+// @acme/layouts — shared layouts and state components.
+export { AuthLayout } from './auth-layout';
+export { Loading } from './states/loading';
+export { AppShellSkeleton } from './states/app-shell-skeleton';
+export { RouteFallback } from './states/route-fallback';
+export { PageSkeleton } from './states/page-skeleton';
+export { Forbidden } from './states/forbidden';
+export { NotFound } from './states/not-found';
+export { Empty } from './states/empty';
+export { StateScreen } from './states/state-screen';
+export { ErrorBoundary } from './error-boundary';
+
+// App shell (Client + Admin)
+export { AppShell } from './app-shell/app-shell';
+export type { NavItem, ComingSoonItem, PreloadRoute } from './app-shell/app-shell';
+export { UserMenu } from './app-shell/user-menu';
+export type { ShellUser } from './app-shell/user-menu';
+
+// Marketing (landing)
+export { MarketingLayout } from './marketing/marketing-layout';
+export { Section } from './marketing/section';
+export type { SectionTone } from './marketing/section';
+export { SectionHeading } from './marketing/section-heading';

package/templates/react-monorepo/files/packages/layouts/src/marketing/marketing-layout.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import { Outlet } from 'react-router';
+
+type MarketingLayoutProps = {
+	/** Sticky header slot (brand, nav, auth CTAs). */
+	header?: ReactNode;
+	/** Footer slot (link columns, legal, newsletter). */
+	footer?: ReactNode;
+	/** Page content. Defaults to the router <Outlet /> when omitted. */
+	children?: ReactNode;
+};
+
+/**
+ * Shared shell for the public marketing site (landing) and its legal pages: a
+ * header slot, the routed page content, and a footer slot — defined once so
+ * nav and footer aren't rebuilt per route. Presentational only, like
+ * `AppShell`: no data fetching, no router coupling beyond the `Outlet`
+ * fallback, and no Suspense of its own — that's the consumer's job, same as
+ * `AppShell` leaves it to `ClientShell`.
+ */
+export function MarketingLayout({ header, footer, children }: MarketingLayoutProps) {
+	return (
+		<div className="flex min-h-screen flex-col bg-background">
+			{header}
+			<main className="flex-1">{children ?? <Outlet />}</main>
+			{footer}
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/marketing/section-heading.tsx

@@ -0,0 +1,38 @@
+import { cn } from '@acme/ui';
+
+type SectionHeadingProps = {
+	eyebrow?: string;
+	title: string;
+	lede?: string;
+	/** `left` drops the centering, for a heading inside a two-column row rather than standing alone. */
+	align?: 'center' | 'left';
+	className?: string;
+};
+
+/**
+ * Eyebrow pill / h2 / lede — the heading stack the design repeats at the top
+ * of most sections. `bg-accent text-accent-foreground` rather than the fixed
+ * `primary-pale` + `ink-deep`: the accent pair flips together per theme, where a
+ * fixed pale badge goes muddy on dark.
+ */
+export function SectionHeading({ eyebrow, title, lede, align = 'center', className }: SectionHeadingProps) {
+	return (
+		<div
+			className={cn(
+				'flex flex-col gap-4',
+				align === 'center' ? 'items-center text-center' : 'items-start text-left',
+				className
+			)}
+		>
+			{eyebrow ? (
+				<span className="inline-flex rounded-full bg-accent px-3.5 py-1.5 text-xs font-bold uppercase tracking-wider text-accent-foreground">
+					{eyebrow}
+				</span>
+			) : null}
+			<h2 className="max-w-3xl font-display text-3xl font-black tracking-tight text-foreground sm:text-4xl lg:text-5xl">
+				{title}
+			</h2>
+			{lede ? <p className="max-w-2xl text-lg text-body">{lede}</p> : null}
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/marketing/section.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import { cn } from '@acme/ui';
+
+export type SectionTone = 'page' | 'band';
+
+type SectionProps = {
+	/** `page` (default) is the plain page background; `band` is the tinted alternate. */
+	tone?: SectionTone;
+	id?: string;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The design alternates the plain page background and a tinted band between
+ * sections. This owns that tone plus the shared 1200px container and vertical
+ * rhythm, so pages reach for a prop instead of one-off classes per section.
+ */
+export function Section({ tone = 'page', id, className, children }: SectionProps) {
+	return (
+		<section
+			id={id}
+			// `scroll-mt` only matters for a section that's also an anchor
+			// target — otherwise the sticky header covers the heading on arrival.
+			className={cn(tone === 'band' ? 'bg-secondary' : 'bg-background', id && 'scroll-mt-20')}
+		>
+			<div className={cn('mx-auto max-w-[1200px] px-5 py-14 sm:py-16 lg:py-24', className)}>{children}</div>
+		</section>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/app-shell-skeleton.tsx

@@ -0,0 +1,47 @@
+import { Logo, Skeleton } from '@acme/ui';
+import { PageSkeleton } from './page-skeleton';
+
+/**
+ * Full-page skeleton for the authenticated bootstrap (session resolving on reload).
+ * Renders the real app-shell chrome — sidebar frame + brand + topbar — so the frame
+ * appears instantly and only nav/content pulse, then hands off to the route's own
+ * skeletons once the shell mounts. Route-agnostic content (used by Client + Admin).
+ */
+export function AppShellSkeleton() {
+	return (
+		<div className="min-h-screen bg-background">
+			{/* Desktop sidebar */}
+			<aside className="fixed inset-y-0 left-0 hidden w-64 border-r border-border bg-card lg:block">
+				<div className="flex h-full flex-col gap-1 p-4">
+					<div className="px-2 py-2">
+						<Logo />
+					</div>
+					<div className="mt-1 flex flex-col gap-1">
+						{Array.from({ length: 6 }).map((_, i) => (
+							<div key={i} className="flex items-center gap-3 px-3 py-2.5">
+								<Skeleton className="size-[18px] rounded-md" />
+								<Skeleton className="h-3.5 w-24" />
+							</div>
+						))}
+					</div>
+				</div>
+			</aside>
+
+			{/* Main column */}
+			<div className="flex min-h-screen flex-col lg:pl-64">
+				<header className="sticky top-0 z-40 flex items-center gap-2.5 border-b border-border bg-card px-4 py-2.5">
+					<Skeleton className="size-9 rounded-full lg:hidden" />
+					<div className="flex-1" />
+					<Skeleton className="size-9 rounded-full" />
+				</header>
+				<main className="flex-1">
+					{/* Same content skeleton a route transition shows, so a reload and a
+					    navigation look identical. */}
+					<div className="mx-auto w-full max-w-6xl p-4 sm:p-6 lg:p-8">
+						<PageSkeleton />
+					</div>
+				</main>
+			</div>
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/empty.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+
+type EmptyProps = {
+	title: string;
+	description?: string;
+	icon?: ReactNode;
+	action?: ReactNode;
+};
+
+/** Inline empty state for lists/panels (a card, not a full page). */
+export function Empty({ title, description, icon, action }: EmptyProps) {
+	return (
+		<div className="flex flex-col items-center justify-center gap-3 rounded-3xl border border-border bg-card p-10 text-center">
+			{icon ? <div className="text-mute">{icon}</div> : null}
+			<div className="flex flex-col gap-1">
+				<p className="font-semibold text-foreground">{title}</p>
+				{description ? <p className="text-sm text-mute">{description}</p> : null}
+			</div>
+			{action}
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/forbidden.tsx

@@ -0,0 +1,14 @@
+import { Button, PageMeta } from '@acme/ui';
+import { StateScreen } from './state-screen';
+
+/** 403 — authenticated but lacking the required role. */
+export function Forbidden({ homeHref = '/' }: { homeHref?: string }) {
+	return (
+		<StateScreen code="403" title="Not authorized" description="You don't have permission to view this page.">
+			<PageMeta title="Not authorized" robots="noindex" />
+			<Button asChild variant="outline">
+				<a href={homeHref}>Go back</a>
+			</Button>
+		</StateScreen>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/loading.tsx

@@ -0,0 +1,11 @@
+import { Spinner } from '@acme/ui';
+
+/** Full-page loading state (route suspense / session bootstrap). */
+export function Loading({ label = 'Loading…' }: { label?: string }) {
+	return (
+		<div className="flex min-h-screen w-full flex-col items-center justify-center gap-3 bg-background text-mute">
+			<Spinner className="size-6" />
+			<span className="text-sm">{label}</span>
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/not-found.tsx

@@ -0,0 +1,21 @@
+import { Button, PageMeta } from '@acme/ui';
+import { StateScreen } from './state-screen';
+
+/** 404 — no matching route. */
+export function NotFound({ homeHref = '/' }: { homeHref?: string }) {
+	return (
+		<StateScreen
+			code="404"
+			title="Page not found"
+			description="The page you're looking for doesn't exist or has moved."
+		>
+			{/* All four apps route here, so the title comes from the shared layer.
+			    `noindex` because a 404 body served at an arbitrary URL should never
+			    be listed — the landing app is public and does get crawled. */}
+			<PageMeta title="Page not found" robots="noindex" />
+			<Button asChild>
+				<a href={homeHref}>Go home</a>
+			</Button>
+		</StateScreen>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/page-skeleton.tsx

@@ -0,0 +1,39 @@
+import { Skeleton } from '@acme/ui';
+
+/**
+ * Route-agnostic placeholder for a page's content area: heading, a summary card,
+ * then a card grid.
+ *
+ * Deliberately the *only* generic loading shape in the app, shared by the
+ * authenticated bootstrap (`AppShellSkeleton`) and by route transitions
+ * (`RouteFallback`). Keeping them identical means a reload and a navigation look
+ * the same, and a route's own skeleton takes over from a shape it already
+ * resembles rather than replacing a different kind of loading indicator.
+ *
+ * Renders no padding or max-width of its own — `AppShell`'s `<main>` already
+ * supplies those, so this can drop straight into the content slot.
+ */
+export function PageSkeleton() {
+	return (
+		<div className="flex flex-col gap-6">
+			<Skeleton className="h-8 w-48" />
+			<div className="flex flex-col gap-5 rounded-3xl bg-card p-6">
+				<Skeleton className="h-4 w-24" />
+				<Skeleton className="h-10 w-52" />
+				<Skeleton className="h-4 w-40" />
+			</div>
+			<div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+				{Array.from({ length: 3 }).map((_, i) => (
+					<div key={i} className="flex flex-col rounded-3xl bg-card p-5">
+						<div className="flex items-start justify-between gap-2">
+							<Skeleton className="h-4 w-28" />
+							<Skeleton className="h-3 w-14" />
+						</div>
+						<Skeleton className="mt-3 h-7 w-32" />
+						<Skeleton className="mt-2 h-3 w-24" />
+					</div>
+				))}
+			</div>
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/route-fallback.tsx

@@ -0,0 +1,26 @@
+import { PageSkeleton } from './page-skeleton';
+
+/**
+ * Suspense fallback for a lazily-loaded route.
+ *
+ * Rendered *inside* the app shell, so the sidebar and topbar stay mounted while
+ * the route's chunk arrives — the user sees the app frame, not a blank page.
+ *
+ * **A skeleton, not a spinner.** A spinner here meant a navigation showed two
+ * different loading languages back to back: spinner while the chunk downloaded,
+ * then the route's own `Skeleton` blocks while its data loaded. Reusing
+ * `PageSkeleton` — the same shape the authenticated bootstrap uses — makes the
+ * whole sequence one continuous skeleton that the route's more specific one
+ * replaces in kind.
+ *
+ * `role="status"` with a visually-hidden label keeps the state announced without
+ * putting a second visible indicator on screen.
+ */
+export function RouteFallback({ label = 'Loading…' }: { label?: string }) {
+	return (
+		<div role="status" aria-busy="true">
+			<span className="sr-only">{label}</span>
+			<PageSkeleton />
+		</div>
+	);
+}

package/templates/react-monorepo/files/packages/layouts/src/states/state-screen.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+
+type StateScreenProps = {
+	code?: string;
+	title: string;
+	description?: string;
+	children?: ReactNode;
+};
+
+/** Full-page centered message used by Forbidden / NotFound / error fallbacks. */
+export function StateScreen({ code, title, description, children }: StateScreenProps) {
+	return (
+		<div className="flex min-h-screen w-full flex-col items-center justify-center gap-4 bg-background p-6 text-center">
+			{code ? <div className="font-display text-6xl font-black text-primary">{code}</div> : null}
+			<div className="flex flex-col gap-1.5">
+				<h1 className="font-display text-2xl font-semibold text-foreground">{title}</h1>
+				{description ? <p className="max-w-sm text-mute">{description}</p> : null}
+			</div>
+			{children ? <div className="flex items-center gap-3">{children}</div> : null}
+		</div>
+	);
+}

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

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

package/templates/react-monorepo/files/packages/types/.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-monorepo/files/packages/types/.bin/secrets.js

@@ -0,0 +1,57 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Pulls this workspace's env from Infisical into the matching .env file.
+// The Infisical path is derived from the package name, e.g.
+//   @scope/types -> /frontend/types, landing -> /frontend/landing
+//
+// The project ID comes from the environment rather than being 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_ROOT = process.env.INFISICAL_PATH_PREFIX ?? '/frontend';
+
+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';
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const slug = pkg.name.replace(/^@[^/]+\//, '');
+const secretPath = `${SECRET_ROOT}/${slug}`;
+
+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 for '${slug}' (${env}) -> ${envFile}...`);
+execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
+	stdio: 'inherit'
+});

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

@@ -0,0 +1,28 @@
+# @acme/types
+
+Generated TypeScript types + Zod schemas from the backend OpenAPI document.
+Consumed by `@acme/api` and the apps, so a stale copy here shows up as a type
+error in an app rather than at runtime.
+
+## Usage
+
+```ts
+import type { UserEntity, GetUsersResponse } from '@acme/types';
+import { zUserEntity } from '@acme/types/zod';
+```
+
+## Regenerating
+
+Requires the backend's docs credentials in `.env` (see `.env.example`).
+
+```bash
+yarn workspace @acme/types gen
+```
+
+That fetches `openapi.json` from the running backend and runs
+`@hey-api/openapi-ts` over it, rewriting `src/types/api/*`. **Commit the
+regenerated files** — they are the contract the apps compile against, and CI
+compares them to the live schema.
+
+`src/types/api/*` ships as an empty placeholder so a freshly scaffolded
+monorepo typechecks before the backend exists. The first `gen` replaces it.

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

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

package/templates/react-monorepo/files/packages/types/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/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-monorepo/files/packages/types/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@acme/types",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./zod": "./src/types/api/zod.gen.ts"
+	},
+	"scripts": {
+		"gen:schema": "node .bin/openapi.js",
+		"gen:types": "openapi-ts",
+		"gen": "node .bin/openapi.js && openapi-ts",
+		"secrets": "node .bin/secrets.js",
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@hey-api/client-fetch": "^0.5.2",
+		"@hey-api/openapi-ts": "^0.59.1",
+		"@acme/config": "workspace:*",
+		"axios": "^1.7.9",
+		"dotenv": "^16.4.7",
+		"tiny-invariant": "^1.3.3"
+	}
+}

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

@@ -0,0 +1,4 @@
+// Public entry for @acme/types.
+// Generated API types live under ./types/api and are refreshed by `yarn gen`.
+export * from './types/api';
+export * from './types/api/zod.gen';

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

@@ -0,0 +1,9 @@
+/**
+ * Placeholder for the generated OpenAPI types.
+ *
+ * `yarn workspace @acme/types gen` fetches the backend's `openapi.json` and
+ * rewrites this directory with `@hey-api/openapi-ts` — overwriting this file.
+ * It exists only so a freshly scaffolded monorepo typechecks before the backend
+ * is running; there is nothing here worth keeping.
+ */
+export {};

package/templates/react-monorepo/files/packages/types/src/types/api/zod.gen.ts

@@ -0,0 +1,5 @@
+/**
+ * Placeholder for the generated Zod schemas. Overwritten by
+ * `yarn workspace @acme/types gen` — see ./index.ts.
+ */
+export {};

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

@@ -0,0 +1,7 @@
+{
+	"extends": "@acme/config/tsconfig/base.json",
+	"compilerOptions": {
+		"lib": ["ES2023", "DOM"]
+	},
+	"include": ["src"]
+}

package/templates/react-monorepo/files/packages/ui/components.json

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "new-york",
+	"rsc": false,
+	"tsx": true,
+	"tailwind": {
+		"config": "",
+		"css": "src/styles/globals.css",
+		"baseColor": "neutral",
+		"cssVariables": true,
+		"prefix": ""
+	},
+	"iconLibrary": "lucide",
+	"aliases": {
+		"components": "@/components",
+		"utils": "@/lib/utils",
+		"ui": "@/components/ui",
+		"lib": "@/lib",
+		"hooks": "@/hooks"
+	}
+}

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

@@ -0,0 +1,13 @@
+import config from '@acme/config/eslint';
+
+export default [
+	...config,
+	{
+		// @acme/ui is a component library consumed as source, not a Vite HMR
+		// boundary — exporting cva variants (buttonVariants) alongside components
+		// is intentional, so the Fast Refresh rule doesn't apply here.
+		rules: {
+			'react-refresh/only-export-components': 'off'
+		}
+	}
+];

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

@@ -0,0 +1,44 @@
+{
+	"name": "@acme/ui",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./globals.css": "./src/styles/globals.css",
+		"./theme-colors": "./src/theme/theme-colors.ts",
+		"./brand": "./src/meta/brand.ts"
+	},
+	"scripts": {
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit"
+	},
+	"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",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"date-fns": "^3",
+		"formik": "^2.4.9",
+		"lucide-react": "^1.17.0",
+		"react-day-picker": "^9",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.6.0",
+		"zod": "^4.4.3",
+		"zod-formik-adapter": "^2.0.0"
+	},
+	"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"
+	}
+}