feat(docs): add AI Coding Agent instructions for universal starter se…

.github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# AI Coding Agent instructions – Universal Starter (Server)
+
+## 📌 Tech Stack
+- **Framework**: [Elysia](https://elysiajs.com/)
+- **Database ORM**: [Prisma](https://www.prisma.io/)
+- **RPC Layer**: [oRPC](https://orpc.dev/) – lightweight, type-safe RPC between server and client
+- **Authentication**: [better-auth](https://better-auth.vercel.app/)
+
+---
+
+## 1. General Rules
+- Always **use TypeScript** with strict typing.
+- Keep imports **absolute** from `src/` using path aliases.
+- Always return **typed responses** from RPC handlers and API routes.
+
+---
+
+## 2. Elysia Guidelines
+- Group related routes in a single Elysia plugin file inside `src/routes/`.
+- When adding middleware:
+  - Use `app.use()` for global middleware.
+  - Use plugin-scoped middleware for route-specific logic.
+
+## 3. Prisma Guidelines
+- Never write raw SQL unless necessary; use Prisma Client for all DB operations.
+- Use select or include to fetch only required fields — avoid findMany() without filters unless needed.
+
+Example:
+
+```typescript
+import { prisma } from '@/src/lib/db';
+
+export const userService = {
+  create: (data: { name: string; email: string }) =>
+    prisma.user.create({ data }),
+
+  findByEmail: (email: string) =>
+    prisma.user.findUnique({
+      where: { email },
+      select: { id: true, name: true, email: true }
+    }),
+};
+```
+
+## 4. oRPC Guidelines
+- Use typed inputs/outputs for every RPC method.
+- Group related RPCs into a single file and export from index.ts

package.json

@@ -10,14 +10,18 @@
     "@better-auth/expo": "^1.3.4",
     "@elysiajs/cors": "^1.3.3",
     "@elysiajs/swagger": "^1.3.1",
+    "@orpc/openapi": "^1.7.10",
+    "@orpc/server": "^1.7.10",
+    "@orpc/zod": "^1.7.10",
     "@plunk/node": "^3.0.3",
     "@prisma/client": "^6.11.1",
     "@prisma/extension-accelerate": "^2.0.1",
     "better-auth": "^1.3.4",
     "elysia": "latest",
     "elysia-rate-limit": "^4.4.0",
     "nodemailer": "^7.0.5",
-    "resend": "^4.8.0"
+    "resend": "^4.8.0",
+    "zod": "^4.0.17"
   },
   "devDependencies": {
     "@biomejs/biome": "2.0.6",

src/index.ts

@@ -4,6 +4,7 @@ import { Elysia } from "elysia";
 import { auth } from "@/src/lib/auth";
 import { isOriginAllowed } from "./cors";
 import { OpenAPI } from "./lib/open-api";
+import { orpcHandler } from "./orpc";
 
 const app = new Elysia()
 	.use(
@@ -55,6 +56,23 @@ const app = new Elysia()
 			},
 		},
 	)
+	// Orpc
+	.all(
+		"/orpc/*",
+		async ({ request }: { request: Request }) => {
+			const { response } = await orpcHandler.handle(request, {
+				prefix: "/orpc",
+				context: {
+					headers: request.headers,
+				},
+			});
+
+			return response ?? new Response("Not Found", { status: 404 });
+		},
+		{
+			parse: "none",
+		},
+	)
 	.listen(3000);
 
 console.log(

src/lib/auth.ts

@@ -29,7 +29,6 @@ export const auth = betterAuth({
 	},
 	emailVerification: {
 		sendVerificationEmail: async ({ user, url, token }, request) => {
-			console.log("Sending verification email to:", user.email);
 			await emailService.sendEmailVerification(user.email, url);
 		},
 		sendOnSignUp: true,

src/lib/email/email-service.ts

@@ -89,7 +89,6 @@ class EmailService {
 		try {
 			// Validate required fields
 			this.validateOptions(options);
-			console.log("Sending email with options:", options);
 			return await this.provider.sendEmail(options);
 		} catch (error) {
 			console.error("Error sending email:", error);

src/lib/email/providers/resend.ts

@@ -30,8 +30,6 @@ export class ResendProvider implements EmailProvider {
 				})),
 			});
 
-			console.log("Email sent successfully:", result.data?.id);
-
 			return {
 				success: true,
 				messageId: result.data?.id,

src/orpc/index.ts

@@ -0,0 +1,31 @@
+import { OpenAPIHandler } from "@orpc/openapi/fetch";
+import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
+// import { CORSPlugin } from "@orpc/server/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod";
+import { appRouter } from "./routers";
+
+export const orpcHandler = new OpenAPIHandler(appRouter, {
+	plugins: [
+		// new CORSPlugin({
+		// 	origin: (origin, options) => origin,
+		// 	allowMethods: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH"],
+		// }),
+		new OpenAPIReferencePlugin({
+			schemaConverters: [new ZodToJsonSchemaConverter()],
+			specGenerateOptions: {
+				info: {
+					title: "ORPC Playground",
+					version: "1.0.0",
+				},
+				components: {
+					securitySchemes: {
+						bearerAuth: {
+							type: "http",
+							scheme: "bearer",
+						},
+					},
+				},
+			},
+		}),
+	],
+});

src/orpc/middleware/auth.middleware.ts

@@ -0,0 +1,58 @@
+import { ORPCError, os } from "@orpc/server";
+import { auth } from "@/src/lib/auth";
+
+type BAUser = typeof auth.$Infer.Session.user | null;
+type BASession = typeof auth.$Infer.Session.session | null;
+
+export type InputCtx = {
+	// initial context must provide request headers
+	headers: Headers | Record<string, string>;
+};
+
+export type AuthCtx = InputCtx & {
+	// injected by middleware
+	user: BAUser;
+	session: BASession;
+};
+
+export const withBetterAuth = os
+	.$context<InputCtx>()
+	.middleware(async ({ context, next }) => {
+		const headers =
+			context.headers instanceof Headers
+				? context.headers
+				: new Headers(context.headers);
+
+		// Server-side Better Auth API (no client in middlewares)
+		const sessionData = await auth.api.getSession({ headers }); // server API call
+
+		return next({
+			context: {
+				// preserve existing context and inject auth data
+				...context,
+				session: sessionData?.session || null,
+				user: sessionData?.user || null,
+			},
+		});
+	});
+
+export const requireAuth = os
+	.$context<AuthCtx>()
+	.middleware(async ({ context, next }) => {
+		if (!context.session || !context.user) {
+			throw new ORPCError("UNAUTHORIZED", { message: "Unauthenticated" });
+		}
+		return next({ context });
+	});
+
+export const requireRole = (roles: string[]) =>
+	os.$context<AuthCtx>().middleware(async ({ context, next }) => {
+		const rolesValue = (context.user as unknown as { roles?: unknown })?.roles;
+		const userRoles: string[] = Array.isArray(rolesValue)
+			? (rolesValue as string[])
+			: [];
+		if (!roles.some((r) => userRoles.includes(r))) {
+			throw new ORPCError("FORBIDDEN", { message: "Forbidden" });
+		}
+		return next({ context });
+	});

src/orpc/middleware/db.middleware.ts

@@ -0,0 +1,18 @@
+import { os } from "@orpc/server";
+import { prisma } from "@/src/lib/db";
+
+export const dbProviderMiddleware = os
+	.$context<{
+		db?: typeof prisma;
+	}>()
+	.middleware(async ({ context, next }) => {
+		const db = context.db ?? prisma;
+
+		return next({
+			context: {
+				// preserve existing context while injecting db
+				...context,
+				db,
+			},
+		});
+	});

src/orpc/middleware/index.ts

@@ -0,0 +1,8 @@
+import { os } from "@orpc/server";
+import { withBetterAuth } from "./auth.middleware";
+import { dbProviderMiddleware } from "./db.middleware";
+
+export const baseMiddleware = os
+	.$context<{ headers: Headers | Record<string, string> }>()
+	.use(dbProviderMiddleware)
+	.use(withBetterAuth);

src/orpc/procedures/user/me.p.ts

@@ -0,0 +1,27 @@
+import { ORPCError } from "@orpc/server";
+import { z } from "zod";
+import { baseMiddleware } from "../../middleware";
+import { requireAuth } from "../../middleware/auth.middleware";
+
+export const meProcedure = baseMiddleware
+	.use(requireAuth)
+	.route({ method: "GET", path: "/user/me" })
+	.output(
+		z.object({
+			id: z.string(),
+			email: z.string(),
+			name: z.string().nullable(),
+		}),
+	)
+	.handler(({ context }) => {
+		const { user } = context;
+		if (!user) {
+			// Should be unreachable because of requireAuth, but keeps types narrow
+			throw new ORPCError("UNAUTHORIZED", { message: "Unauthenticated" });
+		}
+		return {
+			id: user.id,
+			email: user.email,
+			name: user.name ?? null,
+		};
+	});