@codeyam/codeyam-cli 0.1.0-staging.a890816 → 0.1.0-staging.ad88eeb

package/codeyam-cli/templates/nextjs-prisma-sqlite/AUTH_PATTERNS.md

@@ -0,0 +1,308 @@
+# Auth Patterns for Dev Prototyping
+
+This project uses a simple cookie + database auth pattern designed for local development.
+It is **intentionally simple** — built for easy upgrade to a real provider later.
+
+## DO NOT use external auth providers during prototyping
+
+**Do NOT use NextAuth, Auth.js, Clerk, better-auth, Supabase Auth, or any external auth provider.**
+
+These providers require external infrastructure (OAuth endpoints, JWT signing keys, callback URLs)
+that is unavailable in the local SQLite development environment. They will fail silently or produce
+confusing errors. Use the pattern below instead — it works immediately and upgrades cleanly later.
+
+See `AUTH_UPGRADE.md` for how to swap in a real provider when going to production.
+
+## Interfaces
+
+All consumer code imports from `@/app/lib/auth`. The interface is:
+
+```typescript
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+export async function getSession(): Promise<Session | null>;
+export async function requireAuth(): Promise<Session>; // redirects to /login if no session
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null>;
+export async function signOut(): Promise<void>;
+```
+
+## Prisma Schema Additions
+
+Add these models to `prisma/schema.prisma`:
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  name      String
+  email     String    @unique
+  password  String
+  image     String?
+  sessions  Session[]
+  createdAt DateTime  @default(now())
+}
+
+model Session {
+  id        String   @id @default(cuid())
+  token     String   @unique
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+}
+```
+
+After editing the schema, run: `npm run db:push`
+
+## Dev Implementation: `app/lib/auth.ts`
+
+```typescript
+import { cookies } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { prisma } from '@/app/lib/prisma';
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+const COOKIE_NAME = 'session-token';
+
+export async function getSession(): Promise<Session | null> {
+  const cookieStore = await cookies();
+  const token = cookieStore.get(COOKIE_NAME)?.value;
+  if (!token) return null;
+
+  const session = await prisma.session.findUnique({
+    where: { token },
+    include: { user: true },
+  });
+  if (!session) return null;
+
+  return {
+    user: {
+      id: session.user.id,
+      name: session.user.name,
+      email: session.user.email,
+      image: session.user.image,
+    },
+  };
+}
+
+export async function requireAuth(): Promise<Session> {
+  const session = await getSession();
+  if (!session) redirect('/login');
+  return session;
+}
+
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null> {
+  const user = await prisma.user.findUnique({ where: { email } });
+  if (!user || user.password !== password) return null;
+
+  const token = crypto.randomUUID();
+  await prisma.session.create({
+    data: { token, userId: user.id },
+  });
+
+  const cookieStore = await cookies();
+  cookieStore.set(COOKIE_NAME, token, {
+    httpOnly: true,
+    path: '/',
+    sameSite: 'lax',
+  });
+
+  return {
+    user: {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      image: user.image,
+    },
+  };
+}
+
+export async function signOut(): Promise<void> {
+  const cookieStore = await cookies();
+  const token = cookieStore.get(COOKIE_NAME)?.value;
+  if (token) {
+    await prisma.session.deleteMany({ where: { token } });
+  }
+  cookieStore.delete(COOKIE_NAME);
+}
+```
+
+## Cookie Name
+
+The cookie name **must be `session-token`**. The CodeYam proxy uses this name for
+scenario auto-login (injecting/clearing the cookie when switching between scenarios).
+
+## API Routes
+
+### `/api/auth/login` (POST)
+
+```typescript
+import { signIn } from '@/app/lib/auth';
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+  const session = await signIn(email, password);
+  if (!session) {
+    return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 });
+  }
+  return NextResponse.json({ user: session.user });
+}
+```
+
+### `/api/auth/logout` (POST)
+
+```typescript
+import { signOut } from '@/app/lib/auth';
+import { NextResponse } from 'next/server';
+
+export async function POST() {
+  await signOut();
+  return NextResponse.json({ success: true });
+}
+```
+
+### `/api/auth/session` (GET) — for client components
+
+```typescript
+import { getSession } from '@/app/lib/auth';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const session = await getSession();
+  return NextResponse.json({ session });
+}
+```
+
+## Usage in Server Components
+
+```typescript
+import { getSession } from '@/app/lib/auth';
+
+export default async function Dashboard() {
+  const session = await getSession();
+  if (!session) redirect('/login');
+
+  return <h1>Welcome, {session.user.name}</h1>;
+}
+```
+
+## Usage in Client Components
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+
+export function UserNav() {
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    fetch('/api/auth/session')
+      .then(res => res.json())
+      .then(data => setUser(data.session?.user ?? null));
+  }, []);
+
+  if (!user) return <a href="/login">Sign In</a>;
+
+  return (
+    <div>
+      <span>{user.name}</span>
+      <button onClick={() => {
+        fetch('/api/auth/logout', { method: 'POST' })
+          .then(() => window.location.href = '/');
+      }}>
+        Sign Out
+      </button>
+    </div>
+  );
+}
+```
+
+## Login Page Pattern
+
+```typescript
+'use client';
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+
+export default function LoginPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const router = useRouter();
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    const res = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+    if (res.ok) {
+      router.push('/');
+      router.refresh();
+    } else {
+      setError('Invalid email or password');
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="email" value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" required />
+      <input type="password" value={password} onChange={e => setPassword(e.target.value)} placeholder="Password" required />
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      <button type="submit">Sign In</button>
+    </form>
+  );
+}
+```
+
+## Seed Data for Scenarios
+
+When creating scenarios with auth, include both `User` and `Session` rows in seed data:
+
+```json
+{
+  "name": "Logged In User",
+  "type": "application",
+  "url": "/",
+  "seed": {
+    "user": [
+      {
+        "id": "user_1",
+        "name": "Alice",
+        "email": "alice@example.com",
+        "password": "password123"
+      }
+    ],
+    "session": [{ "id": "sess_1", "token": "sess_alice", "userId": "user_1" }]
+  },
+  "session": { "cookieValue": "sess_alice" }
+}
+```
+
+The top-level `"session"` field tells the proxy to set the `session-token` cookie,
+auto-logging the user in when this scenario is active.

package/codeyam-cli/templates/nextjs-prisma-sqlite/AUTH_UPGRADE.md

@@ -0,0 +1,304 @@
+# Upgrading Auth for Production
+
+The dev auth pattern in `app/lib/auth.ts` is designed for easy replacement.
+All consumer code imports from `@/app/lib/auth` — only the internals of that file change.
+
+## What Stays the Same
+
+Every file that imports from `@/app/lib/auth` continues to work unchanged:
+
+- Server components calling `getSession()` and `requireAuth()`
+- Client components fetching `/api/auth/session`
+- API routes using `signIn()` and `signOut()`
+- Login/logout forms
+
+## What Changes
+
+Only `app/lib/auth.ts` internals. Replace the cookie+DB implementation with your chosen provider.
+
+---
+
+## NextAuth v5
+
+### Install
+
+```bash
+npm install next-auth @auth/prisma-adapter
+```
+
+### Replace `app/lib/auth.ts`
+
+```typescript
+import NextAuth from 'next-auth';
+import { PrismaAdapter } from '@auth/prisma-adapter';
+import { prisma } from '@/app/lib/prisma';
+import Credentials from 'next-auth/providers/credentials';
+// Add other providers: Google, GitHub, etc.
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+const {
+  auth,
+  signIn: nextAuthSignIn,
+  signOut: nextAuthSignOut,
+} = NextAuth({
+  adapter: PrismaAdapter(prisma),
+  providers: [
+    Credentials({
+      credentials: { email: {}, password: {} },
+      authorize: async (credentials) => {
+        const user = await prisma.user.findUnique({
+          where: { email: credentials.email as string },
+        });
+        if (!user) return null;
+        // In production, use bcrypt: await bcrypt.compare(password, user.password)
+        return user;
+      },
+    }),
+    // Add: Google({ clientId: ..., clientSecret: ... })
+    // Add: GitHub({ clientId: ..., clientSecret: ... })
+  ],
+  session: { strategy: 'jwt' },
+});
+
+export async function getSession(): Promise<Session | null> {
+  const session = await auth();
+  if (!session?.user) return null;
+  return {
+    user: {
+      id: session.user.id!,
+      name: session.user.name!,
+      email: session.user.email!,
+      image: session.user.image,
+    },
+  };
+}
+
+export async function requireAuth(): Promise<Session> {
+  const session = await getSession();
+  if (!session) {
+    const { redirect } = await import('next/navigation');
+    redirect('/login');
+  }
+  return session;
+}
+
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null> {
+  try {
+    await nextAuthSignIn('credentials', { email, password, redirect: false });
+    return getSession();
+  } catch {
+    return null;
+  }
+}
+
+export async function signOut(): Promise<void> {
+  await nextAuthSignOut({ redirect: false });
+}
+```
+
+### Add route handler
+
+Create `app/api/auth/[...nextauth]/route.ts`:
+
+```typescript
+import { handlers } from '@/app/lib/auth';
+export const { GET, POST } = handlers;
+```
+
+---
+
+## better-auth
+
+### Install
+
+```bash
+npm install better-auth
+```
+
+### Replace `app/lib/auth.ts`
+
+```typescript
+import { betterAuth } from 'better-auth';
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+import { prisma } from '@/app/lib/prisma';
+import { cookies } from 'next/headers';
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+const auth = betterAuth({
+  database: prismaAdapter(prisma, { provider: 'sqlite' }),
+  emailAndPassword: { enabled: true },
+});
+
+export async function getSession(): Promise<Session | null> {
+  const cookieStore = await cookies();
+  const session = await auth.api.getSession({
+    headers: new Headers({ cookie: cookieStore.toString() }),
+  });
+  if (!session?.user) return null;
+  return {
+    user: {
+      id: session.user.id,
+      name: session.user.name,
+      email: session.user.email,
+      image: session.user.image ?? null,
+    },
+  };
+}
+
+export async function requireAuth(): Promise<Session> {
+  const session = await getSession();
+  if (!session) {
+    const { redirect } = await import('next/navigation');
+    redirect('/login');
+  }
+  return session;
+}
+
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null> {
+  try {
+    await auth.api.signInEmail({ body: { email, password } });
+    return getSession();
+  } catch {
+    return null;
+  }
+}
+
+export async function signOut(): Promise<void> {
+  const cookieStore = await cookies();
+  await auth.api.signOut({
+    headers: new Headers({ cookie: cookieStore.toString() }),
+  });
+}
+```
+
+---
+
+## Supabase Auth
+
+### Install
+
+```bash
+npm install @supabase/supabase-js @supabase/ssr
+```
+
+### Replace `app/lib/auth.ts`
+
+```typescript
+import { createServerClient } from '@supabase/ssr';
+import { cookies } from 'next/headers';
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+function createClient() {
+  const cookieStore = cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => cookieStore.then((c) => c.getAll()),
+        setAll: (cookies) =>
+          cookieStore.then((c) => {
+            cookies.forEach(({ name, value, options }) =>
+              c.set(name, value, options),
+            );
+          }),
+      },
+    },
+  );
+}
+
+export async function getSession(): Promise<Session | null> {
+  const supabase = createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  if (!user) return null;
+  return {
+    user: {
+      id: user.id,
+      name: user.user_metadata.name || user.email?.split('@')[0] || '',
+      email: user.email!,
+      image: user.user_metadata.avatar_url ?? null,
+    },
+  };
+}
+
+export async function requireAuth(): Promise<Session> {
+  const session = await getSession();
+  if (!session) {
+    const { redirect } = await import('next/navigation');
+    redirect('/login');
+  }
+  return session;
+}
+
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null> {
+  const supabase = createClient();
+  const { error } = await supabase.auth.signInWithPassword({ email, password });
+  if (error) return null;
+  return getSession();
+}
+
+export async function signOut(): Promise<void> {
+  const supabase = createClient();
+  await supabase.auth.signOut();
+}
+```
+
+### Environment variables
+
+Add to `.env.local`:
+
+```
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+```
+
+---
+
+## After Upgrading
+
+1. Remove the `Session` model from `prisma/schema.prisma` (the provider manages sessions)
+2. Keep the `User` model if your provider uses it, or migrate to the provider's user table
+3. Run `npm run db:push` to apply schema changes
+4. Test sign-in and sign-out flows
+5. Update scenario seed data if the session table structure changed

package/codeyam-cli/templates/nextjs-prisma-sqlite/DATABASE.md

@@ -0,0 +1,112 @@
+# Database
+
+This project uses **Prisma 7 with SQLite** for local development. No external services needed.
+
+All application code imports from `@/app/lib/prisma` — this is the only file that changes when you upgrade to a hosted database.
+
+## Quick Reference
+
+```bash
+# Edit your schema
+vim prisma/schema.prisma
+
+# Push schema changes (also regenerates Prisma client)
+npm run db:push
+
+# Seed demo data
+npm run db:seed
+
+# Reset database (delete + recreate + seed)
+npm run db:reset
+
+# Browse data visually
+npx prisma studio
+```
+
+## Using the Database
+
+```typescript
+import { prisma } from '@/app/lib/prisma';
+
+// In API routes or server components:
+const items = await prisma.todo.findMany();
+const item = await prisma.todo.create({ data: { title: 'New item' } });
+```
+
+## Important: Do NOT Change These Settings
+
+- **Generator must be `prisma-client-js`** (not `prisma-client`). The `prisma-client` generator requires a custom output path that breaks Turbopack.
+- **Do NOT add an `output` field** to the generator.
+- **Do NOT add `url` to the datasource block** in `schema.prisma`. Prisma 7 moved the URL to `prisma.config.ts`.
+- **Keep `serverExternalPackages: ["better-sqlite3"]`** in `next.config.ts`.
+- **Keep `turbopack: { root: "." }`** in `next.config.ts`.
+- **Always run `npx prisma generate`** after `npx prisma db push` (or use `npm run db:push` which does both).
+- **Database file is at project root** (`./dev.db`), not in `prisma/`.
+
+## Upgrading to a Hosted Database
+
+When you're ready for production, you'll want a hosted database. SQLite is great for prototyping, but doesn't support concurrent connections or run in serverless environments (Vercel, etc.).
+
+### Option 1: Supabase (PostgreSQL)
+
+Free tier available. Gives you PostgreSQL + auth + realtime + storage.
+
+1. Create a project at https://supabase.com/dashboard
+2. Get your credentials from Project Settings > Database > Connection string (URI)
+3. Replace packages:
+   ```bash
+   npm uninstall better-sqlite3 @prisma/adapter-better-sqlite3 @types/better-sqlite3
+   npm install @prisma/adapter-pg pg @supabase/supabase-js
+   npm install -D @types/pg
+   ```
+4. Update `prisma/schema.prisma`:
+   ```prisma
+   datasource db {
+     provider = "postgresql"
+   }
+   ```
+5. Update `app/lib/prisma.ts`:
+
+   ```typescript
+   import { PrismaClient } from '@prisma/client';
+   import { PrismaPg } from '@prisma/adapter-pg';
+
+   const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+   const connectionString = process.env.DATABASE_URL!;
+   const adapter = new PrismaPg({ connectionString });
+   export const prisma =
+     globalForPrisma.prisma ?? new PrismaClient({ adapter });
+   if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+   export default prisma;
+   ```
+
+6. Create `.env`:
+   ```
+   DATABASE_URL=postgresql://postgres.YOUR_PROJECT_ID:YOUR_PASSWORD@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+   ```
+7. Remove `serverExternalPackages` from `next.config.ts`
+8. Run `npm run db:push` to create tables in Supabase
+9. Update `prisma/seed.ts` to use the new adapter (same pattern as `prisma.ts`)
+
+### Option 2: Other PostgreSQL Hosts (Neon, Railway, etc.)
+
+Same steps as Supabase above (steps 3-9), just use your provider's connection string.
+
+### Option 3: PlanetScale / MySQL
+
+1. Replace packages:
+   ```bash
+   npm uninstall better-sqlite3 @prisma/adapter-better-sqlite3 @types/better-sqlite3
+   npm install @prisma/adapter-planetscale @planetscale/database
+   ```
+2. Update `schema.prisma` datasource to `provider = "mysql"`
+3. Update `app/lib/prisma.ts` to use `PrismaPlanetScale` adapter
+4. Follow PlanetScale setup docs for connection string
+
+### What Stays the Same
+
+Your application code doesn't change at all. Every file that uses the database already imports from `@/app/lib/prisma`, which is the only file that gets updated. Your Prisma schema models, API routes, and server components all work identically regardless of which database backs them.
+
+## Writing Seed Scripts
+
+Seed scripts run outside of Next.js, so they must create their own PrismaClient with the adapter (they cannot import from `@/app/lib/prisma`). See `prisma/seed.ts` for the correct pattern.