@0x0501/mystack 0.0.0-stage → 0.1.0-bootstrap.0

package/template/src/db/index.ts

@@ -0,0 +1,15 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import * as schema from "@/db/schema";
+
+export function createDB(connection: Hyperdrive) {
+	const client = new Pool({
+		connectionString: connection.connectionString,
+	});
+
+	return drizzle(client, { schema });
+}
+
+export type Database = ReturnType<typeof createDB>;
+export type DatabaseTxCallback = Parameters<Database["transaction"]>[0];
+export type DatabaseTx = Parameters<DatabaseTxCallback>[0];

package/template/src/db/platform.schema.ts

@@ -0,0 +1,122 @@
+/**
+ * Platform tables owned by the Starter (not Better Auth generated).
+ * Purchase, audit log, system_config — product domain tables stay out.
+ */
+import { sql } from "drizzle-orm";
+import {
+	index,
+	jsonb,
+	pgPolicy,
+	pgRole,
+	pgTable,
+	text,
+	timestamp,
+	uniqueIndex,
+} from "drizzle-orm/pg-core";
+import { user } from "./auth.schema";
+
+/** App role used by Hyperdrive connections (RLS policies target this). */
+export const appRole = pgRole("starter_app", { createRole: false }).existing();
+
+export type JsonValue =
+	| string
+	| number
+	| boolean
+	| null
+	| { [key: string]: JsonValue }
+	| JsonValue[];
+
+export const systemConfig = pgTable(
+	"system_config",
+	{
+		key: text("key").primaryKey(),
+		value: jsonb("value").$type<JsonValue>().notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.$onUpdate(() => new Date())
+			.notNull(),
+	},
+	() => [
+		pgPolicy("rls_policy", {
+			as: "permissive",
+			to: appRole,
+			for: "all",
+			using: sql`app_private.is_admin()`,
+			withCheck: sql`app_private.is_admin()`,
+		}),
+	],
+);
+
+export const adminAction = pgTable(
+	"admin_action",
+	{
+		id: text("id").primaryKey(),
+		actorId: text("actor_id").references(() => user.id, {
+			onDelete: "set null",
+		}),
+		action: text("action").notNull(),
+		targetType: text("target_type"),
+		targetId: text("target_id"),
+		detail: jsonb("detail").$type<JsonValue>(),
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(t) => [
+		pgPolicy("rls_policy", {
+			as: "permissive",
+			to: appRole,
+			for: "all",
+			using: sql`app_private.is_admin()`,
+			withCheck: sql`app_private.is_admin()`,
+		}),
+		index("admin_action_created_idx").on(t.createdAt.desc()),
+	],
+);
+
+export const purchase = pgTable(
+	"purchase",
+	{
+		id: text("id").primaryKey(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => user.id, { onDelete: "cascade" }),
+		provider: text("provider").notNull(), // stripe | creem | nowpayments
+		externalId: text("external_id").notNull(),
+		// Minor units as decimal text (e.g. "1999" cents). Avoid float JSON;
+		// adapters parse with parseInt, not Number(), for safe integers.
+		amount: text("amount").notNull(),
+		currency: text("currency").notNull().default("usd"),
+		status: text("status").notNull().default("pending"), // pending | paid | failed
+		metadata: jsonb("metadata").$type<JsonValue>(),
+		paidAt: timestamp("paid_at", { withTimezone: true }),
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.$onUpdate(() => new Date())
+			.notNull(),
+	},
+	(t) => [
+		uniqueIndex("purchase_provider_external_uq").on(t.provider, t.externalId),
+		index("purchase_userId_idx").on(t.userId),
+		pgPolicy("rls_user_read", {
+			as: "permissive",
+			to: appRole,
+			for: "select",
+			using: sql`app_private.is_admin() OR user_id = app_private.current_user_id()`,
+		}),
+		pgPolicy("rls_service_write", {
+			as: "permissive",
+			to: appRole,
+			for: "all",
+			using: sql`app_private.is_admin()`,
+			withCheck: sql`app_private.is_admin()`,
+		}),
+	],
+);
+
+export type SystemConfigRow = typeof systemConfig.$inferSelect;
+export type AdminActionRow = typeof adminAction.$inferSelect;
+export type PurchaseRow = typeof purchase.$inferSelect;

package/template/src/db/schema.ts

@@ -0,0 +1,2 @@
+export * from "./auth.schema";
+export * from "./platform.schema";

package/template/src/env.ts

@@ -0,0 +1,65 @@
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+function createAppEnv() {
+	return createEnv({
+		server: {
+			APP_ORIGIN: z.url(),
+			SERVER_URL: z.url().optional(),
+			BETTER_AUTH_URL: z.url(),
+			BETTER_AUTH_SECRET: z.string().min(1),
+			// Comma-separated OAuth resource audiences; empty defaults to APP_ORIGIN.
+			BETTER_AUTH_AUDIENCES: z.string().optional(),
+			TURNSTILE_SECRET_KEY: z.string().optional(),
+			EMAIL_FROM: z.string().min(1),
+			/** Inbox From display name — clone-time brand string. */
+			EMAIL_FROM_NAME: z.string().min(1).default("Starter"),
+
+			GITHUB_CLIENT_ID: z.string().optional(),
+			GITHUB_CLIENT_SECRET: z.string().optional(),
+
+			// Optional payment adapters — absence means inactive.
+			CREEM_API_KEY: z.string().optional(),
+			CREEM_WEBHOOK_SECRET: z.string().optional(),
+			CREEM_PRODUCT_ID: z.string().optional(),
+			CREEM_TEST_MODE: z.stringbool().default(false),
+
+			STRIPE_SECRET_KEY: z.string().optional(),
+			STRIPE_WEBHOOK_SECRET: z.string().optional(),
+
+			NOW_PAYMENTS_API_KEY: z.string().optional(),
+			NOW_PAYMENTS_IPN_KEY: z.string().optional(),
+			NOW_PAYMENTS_TEST_MODE: z.stringbool().default(false),
+		},
+
+		clientPrefix: "VITE_",
+
+		client: {
+			VITE_APP_TITLE: z.string().min(1).optional(),
+			VITE_APP_ORIGIN: z.url().optional(),
+			VITE_TURNSTILE_SITE_KEY: z.string().min(1).optional(),
+			// Public GitHub OAuth client id (same value as GITHUB_CLIENT_ID).
+			// When set with GITHUB_CLIENT_SECRET, the provider is enabled end-to-end.
+			VITE_GITHUB_CLIENT_ID: z.string().min(1).optional(),
+		},
+
+		runtimeEnv: process.env,
+		emptyStringAsUndefined: true,
+	});
+}
+
+type AppEnv = ReturnType<typeof createAppEnv>;
+
+let appEnv: AppEnv | undefined;
+
+export function getEnv() {
+	if (!appEnv) appEnv = createAppEnv();
+	return appEnv;
+}
+
+/** Lazy proxy so importing modules does not force env validation at load time in tests. */
+export const env = new Proxy({} as AppEnv, {
+	get(_target, prop, receiver) {
+		return Reflect.get(getEnv(), prop, receiver);
+	},
+});

package/template/src/hooks/use-theme.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+import {
+	applyTheme,
+	readThemePreference,
+	type ThemePreference,
+} from "@/lib/theme";
+
+/** Theme behavior shared by the supplied control and custom presentations. */
+export function useTheme() {
+	const [preference, setPreference] = useState<ThemePreference>("system");
+	const [mounted, setMounted] = useState(false);
+
+	useEffect(() => {
+		setPreference(readThemePreference());
+		setMounted(true);
+	}, []);
+
+	useEffect(() => {
+		if (!mounted || preference !== "system") return;
+		const query = window.matchMedia("(prefers-color-scheme: dark)");
+		const onChange = () => applyTheme("system");
+		query.addEventListener("change", onChange);
+		return () => query.removeEventListener("change", onChange);
+	}, [mounted, preference]);
+
+	function setTheme(next: ThemePreference) {
+		setPreference(next);
+		applyTheme(next);
+	}
+
+	return { preference, setTheme, mounted };
+}

package/template/src/integrations/better-auth/header-user.tsx

@@ -0,0 +1,36 @@
+import { authClient } from "@/lib/auth-client";
+
+export default function BetterAuthHeader() {
+	const { data: session, isPending } = authClient.useSession();
+
+	if (isPending) {
+		return <div className="h-8 w-8 bg-muted animate-pulse" />;
+	}
+
+	if (session?.user) {
+		return (
+			<div className="flex items-center gap-2">
+				{session.user.image ? (
+					<img src={session.user.image} alt="" className="h-8 w-8" />
+				) : (
+					<div className="h-8 w-8 bg-muted flex items-center justify-center">
+						<span className="text-xs font-medium text-muted-foreground">
+							{session.user.name?.charAt(0).toUpperCase() || "U"}
+						</span>
+					</div>
+				)}
+				<button
+					type="button"
+					onClick={() => {
+						void authClient.signOut();
+					}}
+					className="flex-1 h-9 px-4 text-sm font-medium bg-background text-muted-foreground border border-border hover:bg-muted dark:hover:bg-muted transition-colors"
+				>
+					Sign out
+				</button>
+			</div>
+		);
+	}
+
+	return null;
+}

package/template/src/integrations/better-auth/session-query.ts

@@ -0,0 +1,11 @@
+import { queryOptions } from "@tanstack/react-query";
+import { getSession } from "@/server/auth";
+
+/** Shared by root guards; fetchQuery revalidates stale or invalidated sessions. */
+export const sessionQueryOptions = queryOptions({
+	queryKey: ["auth", "session"],
+	queryFn: () => getSession(),
+	staleTime: 30_000,
+	// Keep a failed session check from holding navigation through retry backoff.
+	retry: false,
+});

package/template/src/integrations/react-email/PasswordOtpEmail.tsx

@@ -0,0 +1,62 @@
+import {
+	Body,
+	Container,
+	Head,
+	Heading,
+	Hr,
+	Html,
+	Preview,
+	Text,
+} from "@react-email/components";
+
+import * as m from "@/paraglide/messages";
+import * as s from "./theme.ts";
+
+/** See `VerifyEmail` for why `locale` is a prop rather than ambient state. */
+export function PasswordOtpEmail({
+	otp,
+	brandName,
+	purpose,
+	locale,
+}: {
+	otp: string;
+	brandName: string;
+	purpose: "forget-password" | "sign-in";
+	locale?: "en" | "de";
+}) {
+	const opts = { locale };
+	const reset = purpose === "forget-password";
+	const preview = reset
+		? m.email_otp_preview_reset({ brand: brandName }, opts)
+		: m.email_otp_preview_signin({ brand: brandName }, opts);
+	const heading = reset
+		? m.email_otp_heading_reset({}, opts)
+		: m.email_otp_heading_signin({}, opts);
+
+	return (
+		<Html lang={locale ?? "en"}>
+			<Head />
+			<Preview>{preview}</Preview>
+			<Body style={s.main}>
+				<Container style={s.container}>
+					<Text style={s.wordmark}>{brandName}</Text>
+					<Heading style={s.heading}>{heading}</Heading>
+					<Text style={s.text}>{m.email_otp_body({}, opts)}</Text>
+					<Text style={s.otpCode}>{otp}</Text>
+					<Hr style={s.hr} />
+					<Text style={s.footer}>
+						{m.email_otp_footer({ brand: brandName }, opts)}
+					</Text>
+				</Container>
+			</Body>
+		</Html>
+	);
+}
+
+PasswordOtpEmail.PreviewProps = {
+	otp: "123456",
+	brandName: "Starter",
+	purpose: "sign-in" as const,
+};
+
+export default PasswordOtpEmail;

package/template/src/integrations/react-email/ResetPasswordEmail.tsx

@@ -0,0 +1,64 @@
+import {
+	Body,
+	Button,
+	Container,
+	Head,
+	Heading,
+	Hr,
+	Html,
+	Preview,
+	Section,
+	Text,
+} from "@react-email/components";
+
+import * as m from "@/paraglide/messages";
+import * as s from "./theme.ts";
+
+/** See `VerifyEmail` for why `locale` is a prop rather than ambient state. */
+export function ResetPasswordEmail({
+	url,
+	name,
+	brandName,
+	locale,
+}: {
+	url: string;
+	name?: string;
+	brandName: string;
+	locale?: "en" | "de";
+}) {
+	const opts = { locale };
+	return (
+		<Html lang={locale ?? "en"}>
+			<Head />
+			<Preview>{m.email_reset_preview({ brand: brandName }, opts)}</Preview>
+			<Body style={s.main}>
+				<Container style={s.container}>
+					<Text style={s.wordmark}>{brandName}</Text>
+					<Heading style={s.heading}>{m.email_reset_heading({}, opts)}</Heading>
+					<Text style={s.text}>
+						{name
+							? m.email_reset_body_named({ name, brand: brandName }, opts)
+							: m.email_reset_body({ brand: brandName }, opts)}
+					</Text>
+					<Section style={{ textAlign: "center", margin: "32px 0 4px" }}>
+						<Button href={url} style={s.button}>
+							{m.email_reset_cta({}, opts)}
+						</Button>
+					</Section>
+					<Text style={s.text}>{m.email_link_fallback({}, opts)}</Text>
+					<Text style={s.linkText}>{url}</Text>
+					<Hr style={s.hr} />
+					<Text style={s.footer}>{m.email_reset_footer({}, opts)}</Text>
+				</Container>
+			</Body>
+		</Html>
+	);
+}
+
+ResetPasswordEmail.PreviewProps = {
+	url: "https://example.com/reset-password?token=preview-token",
+	name: "Ada",
+	brandName: "Starter",
+};
+
+export default ResetPasswordEmail;

package/template/src/integrations/react-email/VerifyEmail.tsx

@@ -0,0 +1,72 @@
+import {
+	Body,
+	Button,
+	Container,
+	Head,
+	Heading,
+	Hr,
+	Html,
+	Preview,
+	Section,
+	Text,
+} from "@react-email/components";
+
+import * as m from "@/paraglide/messages";
+import * as s from "./theme.ts";
+
+/**
+ * `locale` is passed explicitly rather than read from ambient state: an email
+ * is rendered inside a request whose own locale is the sender's, not the
+ * recipient's. It is the account's stored `user.locale` (ADR 0005).
+ */
+export function VerifyEmail({
+	url,
+	name,
+	brandName,
+	locale,
+}: {
+	url: string;
+	name?: string;
+	brandName: string;
+	locale?: "en" | "de";
+}) {
+	const opts = { locale };
+	return (
+		<Html lang={locale ?? "en"}>
+			<Head />
+			<Preview>{m.email_verify_preview({ brand: brandName }, opts)}</Preview>
+			<Body style={s.main}>
+				<Container style={s.container}>
+					<Text style={s.wordmark}>{brandName}</Text>
+					<Heading style={s.heading}>
+						{m.email_verify_heading({}, opts)}
+					</Heading>
+					<Text style={s.text}>
+						{name
+							? m.email_verify_body_named({ name }, opts)
+							: m.email_verify_body({}, opts)}
+					</Text>
+					<Section style={{ textAlign: "center", margin: "32px 0 4px" }}>
+						<Button href={url} style={s.button}>
+							{m.email_verify_cta({}, opts)}
+						</Button>
+					</Section>
+					<Text style={s.text}>{m.email_link_fallback({}, opts)}</Text>
+					<Text style={s.linkText}>{url}</Text>
+					<Hr style={s.hr} />
+					<Text style={s.footer}>
+						{m.email_verify_footer({ brand: brandName }, opts)}
+					</Text>
+				</Container>
+			</Body>
+		</Html>
+	);
+}
+
+VerifyEmail.PreviewProps = {
+	url: "https://example.com/api/auth/verify-email?token=preview-token",
+	name: "Ada",
+	brandName: "Starter",
+};
+
+export default VerifyEmail;

package/template/src/integrations/react-email/theme.ts

@@ -0,0 +1,75 @@
+// Shared email styles. Email clients need inline styles and web-safe fonts.
+// Neutral structural palette only — clones rebrand for product identity.
+export const serif = "Georgia, 'Times New Roman', Times, serif";
+
+export const main = {
+	backgroundColor: "#f4f4f5",
+	margin: 0,
+	// Horizontal padding keeps the card off the screen edges on small devices.
+	padding: "32px 16px",
+	fontFamily: serif,
+};
+export const container = {
+	maxWidth: "480px",
+	margin: "0 auto",
+	backgroundColor: "#ffffff",
+	border: "1px solid #e4e4e7",
+	borderRadius: "4px",
+	padding: "40px 40px 32px",
+};
+export const wordmark = {
+	margin: 0,
+	fontFamily: serif,
+	fontSize: "22px",
+	fontWeight: 600,
+	letterSpacing: "0.01em",
+	color: "#18181b",
+};
+export const heading = {
+	margin: "24px 0 0",
+	fontFamily: serif,
+	fontSize: "26px",
+	fontWeight: 600,
+	color: "#18181b",
+};
+export const text = {
+	margin: "12px 0 0",
+	fontSize: "16px",
+	lineHeight: "1.6",
+	color: "#52525b",
+};
+export const button = {
+	backgroundColor: "#18181b",
+	color: "#fafafa",
+	fontFamily: serif,
+	fontSize: "16px",
+	fontWeight: 600,
+	textDecoration: "none",
+	padding: "12px 28px",
+	borderRadius: "3px",
+	display: "inline-block",
+};
+export const linkText = {
+	margin: "8px 0 0",
+	fontSize: "13px",
+	lineHeight: "1.5",
+	color: "#3f3f46",
+	wordBreak: "break-all" as const,
+};
+export const hr = { borderColor: "#e4e4e7", margin: "28px 0 0" };
+export const footer = {
+	margin: "16px 0 0",
+	fontSize: "13px",
+	lineHeight: "1.6",
+	color: "#71717a",
+};
+export const otpCode = {
+	margin: "20px 0 0",
+	fontFamily:
+		"ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+	fontSize: "28px",
+	fontWeight: 600,
+	letterSpacing: "0.2em",
+	color: "#18181b",
+	textAlign: "center" as const,
+};

package/template/src/integrations/tanstack-query/devtools.tsx

@@ -0,0 +1,6 @@
+import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools";
+
+export default {
+	name: "Tanstack Query",
+	render: <ReactQueryDevtoolsPanel />,
+};

package/template/src/integrations/tanstack-query/root-provider.tsx

@@ -0,0 +1,60 @@
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import type { RootSession } from "@/server/auth";
+import { HttpError } from "@/utils/api-error";
+import { goToSignIn } from "@/utils/auth-redirect";
+
+export interface MyRouterContext {
+	queryClient: QueryClient;
+	/** Filled by root `beforeLoad` — one session read per request. */
+	session?: RootSession | null;
+}
+
+/**
+ * The one place an expired session is handled.
+ *
+ * Every guarded server function throws a 401 the same way, so the remedy
+ * belongs here rather than in each page that consumes one — a component
+ * whose query 401s has no better answer than the sign-in page.
+ */
+function handleClientDataError(error: unknown) {
+	if (typeof window === "undefined") return;
+
+	if (error instanceof HttpError && error.status === 401) {
+		goToSignIn(`${window.location.pathname}${window.location.search}`);
+	}
+}
+
+export function getContext(): MyRouterContext {
+	const queryClient = new QueryClient({
+		defaultOptions: {
+			queries: {
+				// Reuse SSR/loader/preload results on mount rather than immediately
+				// repeating the same server function. Pages can override freshness.
+				staleTime: 30_000,
+				// A 4xx is a refusal, not a flake: asking again gets the same
+				// answer, and for a 401 the default three retries held the user
+				// on a dead page through ~7s of backoff before the redirect
+				// above could fire. Everything else — network faults, 5xx —
+				// keeps the default three attempts.
+				retry: (failureCount, error) =>
+					!(
+						error instanceof HttpError &&
+						error.status >= 400 &&
+						error.status < 500
+					) && failureCount < 3,
+			},
+		},
+		queryCache: new QueryCache({
+			onError: (error) => handleClientDataError(error),
+		}),
+		mutationCache: new MutationCache({
+			onError: (error) => handleClientDataError(error),
+		}),
+	});
+
+	return {
+		queryClient,
+	};
+}
+
+export default function TanstackQueryProvider() {}

package/template/src/lib/auth-client.ts

@@ -0,0 +1,27 @@
+import { oauthProviderClient } from "@better-auth/oauth-provider/client";
+import { passkeyClient } from "@better-auth/passkey/client";
+import {
+	adminClient,
+	inferAdditionalFields,
+	twoFactorClient,
+} from "better-auth/client/plugins";
+import { createAuthClient } from "better-auth/react";
+// Type-only import: a value import would drag server-only code into the client.
+import type { auth } from "@/lib/auth";
+import { localizedAuthPath } from "@/utils/auth-redirect";
+import { ac, admin, superadmin, user } from "./permissions";
+
+export const authClient = createAuthClient({
+	plugins: [
+		adminClient({ ac, roles: { admin, superadmin, user } }),
+		oauthProviderClient(),
+		passkeyClient(),
+		twoFactorClient({
+			onTwoFactorRedirect() {
+				// Locale-prefixed challenge page so full-app URL i18n is preserved.
+				window.location.href = `${localizedAuthPath("/two-factor")}${window.location.search}`;
+			},
+		}),
+		inferAdditionalFields<typeof auth>(),
+	],
+});