@dennisrongo/skills 0.1.2 → 0.2.0

package/skills/nextjs-app-router/references/templates/nextauth-config.md

@@ -0,0 +1,178 @@
+# NextAuth (Auth.js v5) configuration
+
+Two files, by design:
+
+- **`src/auth.config.ts`** — Edge-safe. Providers, callbacks, page mappings. **No DB imports.** Consumed by `middleware.ts`.
+- **`src/auth.ts`** — full config. Imports `auth.config.ts`, adds the Prisma adapter, adds `authorize` for Credentials (which needs `db` + `bcryptjs`). Consumed by Route Handlers and server components.
+
+The split is mandatory because middleware runs on the Edge runtime, which can't import the Prisma client (Node-only). Collapsing them produces a confusing "module not found in edge runtime" error at build time.
+
+## `src/auth.config.ts` (EDGE-SAFE)
+
+```ts
+import type { NextAuthConfig } from 'next-auth';
+import Credentials from 'next-auth/providers/credentials';
+// import GitHub from 'next-auth/providers/github';   // uncomment if enabled in Step 2
+// import Google from 'next-auth/providers/google';   // uncomment if enabled in Step 2
+
+export default {
+  providers: [
+    Credentials({
+      // The `authorize` function lives in src/auth.ts (it needs DB + bcryptjs).
+      // Here we only declare the credentials shape so the provider is registered for type inference.
+      credentials: {
+        email: { label: 'Email', type: 'email' },
+        password: { label: 'Password', type: 'password' },
+      },
+    }),
+    // GitHub({ clientId: process.env.AUTH_GITHUB_ID!, clientSecret: process.env.AUTH_GITHUB_SECRET! }),
+    // Google({ clientId: process.env.AUTH_GOOGLE_ID!, clientSecret: process.env.AUTH_GOOGLE_SECRET! }),
+  ],
+  pages: {
+    signIn: '/auth/login',
+    error: '/auth/error',
+  },
+  callbacks: {
+    authorized({ auth, request: { nextUrl } }) {
+      const isLoggedIn = !!auth?.user;
+      const onPublic = nextUrl.pathname.startsWith('/auth');
+      const onApp = nextUrl.pathname.startsWith('/app');
+      const onAdmin = nextUrl.pathname.startsWith('/admin');
+
+      if (onPublic) {
+        return isLoggedIn ? Response.redirect(new URL('/app/dashboard', nextUrl)) : true;
+      }
+      if (onApp || onAdmin) {
+        return isLoggedIn; // false → redirect to pages.signIn
+      }
+      return true;
+    },
+    async jwt({ token, user }) {
+      if (user) {
+        token.id = user.id as string;
+        // Add `role` here if the User model has one:
+        // if ('role' in user) token.role = user.role as string;
+      }
+      return token;
+    },
+    async session({ session, token }) {
+      if (token?.id && session.user) {
+        session.user.id = token.id as string;
+        // if (token.role) session.user.role = token.role as string;
+      }
+      return session;
+    },
+  },
+} satisfies NextAuthConfig;
+```
+
+**Edge-safety checklist for this file:**
+
+- No `import { db } from '@/lib/db'`.
+- No `import { PrismaAdapter } from '@auth/prisma-adapter'`.
+- No `import bcrypt from 'bcryptjs'`.
+- No `import { auth } from '@/auth'` (circular).
+
+## `src/auth.ts` (full config, Node-only)
+
+```ts
+import NextAuth from 'next-auth';
+import Credentials from 'next-auth/providers/credentials';
+import { PrismaAdapter } from '@auth/prisma-adapter';
+import bcrypt from 'bcryptjs';
+import { z } from 'zod';
+import { db } from '@/lib/db';
+import authConfig from './auth.config';
+
+const credentialsSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  ...authConfig,
+  adapter: PrismaAdapter(db),
+  // JWT strategy is REQUIRED when Credentials is one of the providers.
+  // Database sessions don't work with Credentials by NextAuth design.
+  session: { strategy: 'jwt' },
+  providers: [
+    // Re-declare Credentials here with the real `authorize` (which needs db + bcrypt).
+    Credentials({
+      credentials: {
+        email: { label: 'Email', type: 'email' },
+        password: { label: 'Password', type: 'password' },
+      },
+      async authorize(rawCredentials) {
+        const parsed = credentialsSchema.safeParse(rawCredentials);
+        if (!parsed.success) return null;
+
+        const user = await db.user.findUnique({
+          where: { email: parsed.data.email },
+          select: { id: true, email: true, name: true, image: true, password: true, role: true },
+        });
+        if (!user?.password) return null;
+
+        const ok = await bcrypt.compare(parsed.data.password, user.password);
+        if (!ok) return null;
+
+        return {
+          id: user.id,
+          email: user.email,
+          name: user.name,
+          image: user.image,
+          role: user.role,
+        };
+      },
+    }),
+    // Any OAuth providers from authConfig.providers carry over via the spread above —
+    // re-declare them here only if they need server-only secrets that auth.config.ts couldn't see.
+  ],
+});
+```
+
+## `src/app/api/auth/[...nextauth]/route.ts`
+
+```ts
+export { GET, POST } from '@/auth';
+```
+
+That's the entire file. NextAuth's `handlers` is `{ GET, POST }`, and `auth.ts` re-exports them. The catch-all route gets every `/api/auth/*` request (sign-in, callback, CSRF, session, etc.).
+
+## `src/types/next-auth.d.ts`
+
+```ts
+import 'next-auth';
+import 'next-auth/jwt';
+
+declare module 'next-auth' {
+  interface Session {
+    user: {
+      id: string;
+      email: string;
+      name?: string | null;
+      image?: string | null;
+      role?: string;
+    };
+  }
+
+  interface User {
+    id: string;
+    role?: string;
+  }
+}
+
+declare module 'next-auth/jwt' {
+  interface JWT {
+    id: string;
+    role?: string;
+  }
+}
+```
+
+Without this file, TypeScript thinks `session.user.id` is `undefined`.
+
+## Forbidden in `auth.config.ts`
+
+- Importing `@/lib/db`, `@/auth`, `@auth/prisma-adapter`, `bcryptjs`, or anything that pulls in Node-only modules.
+- Defining the Credentials `authorize` here (it needs the DB).
+- Any logic that calls `cookies()` or `headers()` from `next/headers` — those are server-only.

package/skills/nextjs-app-router/references/templates/package.md

@@ -19,13 +19,27 @@ Resolve **every** version via context7 at scaffold time. Versions below are plac
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
+    "db:generate": "prisma generate",
+    "db:migrate": "prisma migrate dev",
+    "db:migrate:deploy": "prisma migrate deploy",
+    "db:studio": "prisma studio",
+    "db:seed": "tsx prisma/seed.ts",
     "prepare": "husky"
   },
+  "prisma": {
+    "seed": "tsx prisma/seed.ts"
+  },
   "dependencies": {
     "next": "^x.y.z",
     "react": "^x.y.z",
     "react-dom": "^x.y.z",
 
+    "next-auth": "^x.y.z",
+    "@auth/prisma-adapter": "^x.y.z",
+    "bcryptjs": "^x.y.z",
+
+    "@prisma/client": "^x.y.z",
+
     "@reduxjs/toolkit": "^x.y.z",
     "react-redux": "^x.y.z",
 
@@ -54,6 +68,10 @@ Resolve **every** version via context7 at scaffold time. Versions below are plac
     "@types/node": "^x.y.z",
     "@types/react": "^x.y.z",
     "@types/react-dom": "^x.y.z",
+    "@types/bcryptjs": "^x.y.z",
+
+    "prisma": "^x.y.z",
+    "tsx": "^x.y.z",
 
     "tailwindcss": "^x.y.z",
     "postcss": "^x.y.z",
@@ -81,19 +99,31 @@ Resolve **every** version via context7 at scaffold time. Versions below are plac
   },
   "lint-staged": {
     "*.{ts,tsx}": ["prettier --write", "eslint --fix"],
-    "*.{json,md,css,yml,yaml}": ["prettier --write"]
+    "*.{json,md,css,yml,yaml,prisma}": ["prettier --write"]
   }
 }
 ```
 
-**Do NOT include:**
+## Notes on version resolution
+
+- **`next-auth`**: Auth.js v5 (the version with the `handlers`/`auth`/`signIn`/`signOut` exports). Check context7 for the current version line — at certain points this is published under a `@beta` tag. Quote the resolved version back to the user before installing.
+- **`bcryptjs` vs `bcrypt` vs `@node-rs/argon2`**: pure-JS `bcryptjs` is the safest default — it works on every Node version and in serverless without native bindings. Switch to `@node-rs/argon2` only if the user explicitly asks for Argon2 and confirms their deploy target supports native bindings.
+- **`tsx`** is for running `prisma/seed.ts` and any TypeScript scripts without a build step.
+
+## Do NOT include
+
 - `moment` (use `date-fns`)
-- `styled-components` / `@emotion/*` (project is Tailwind-only)
+- `styled-components` / `@emotion/*` (Tailwind only)
 - `nprogress` (use `next-nprogress-bar`)
-- A `proxy` library at the application layer (use Next.js `rewrites()` in `next.config.ts`)
+- `jsonwebtoken` or `jose` for the application layer — NextAuth handles JWT signing/verification internally
+- `js-cookie` — NextAuth manages the session cookie
+- A second auth library (`Clerk`, `Lucia`, `Iron Session`, etc.) alongside NextAuth
+- A second ORM (`Drizzle`, `Kysely`, `TypeORM`) alongside Prisma
+
+## Add only if the user opted in during Step 2
 
-**Add only if the user opted in during Step 2:**
 - `pusher-js` (real-time)
 - Storybook packages
 - `next-intl` / `next-i18next` (i18n)
 - `@sentry/nextjs` (error tracking)
+- `@auth/core` providers not in the default install (e.g. specific OAuth providers shipped separately)

package/skills/nextjs-app-router/references/templates/prisma-schema.md

@@ -0,0 +1,162 @@
+# Prisma schema (NextAuth + domain)
+
+One `schema.prisma` file holds the NextAuth tables (so the Prisma adapter works) plus your domain models. Verify field shapes against the current `@auth/prisma-adapter` docs via context7 at scaffold time — the adapter's required columns evolve.
+
+## `prisma/schema.prisma`
+
+```prisma
+// This file is the source of truth for the database schema.
+// Every change goes through `pnpm exec prisma migrate dev --name <slug>`.
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// ---------- NextAuth tables ----------
+// Shape required by @auth/prisma-adapter. Verify against current adapter docs.
+
+model User {
+  id            String    @id @default(cuid())
+  name          String?
+  email         String    @unique
+  emailVerified DateTime?
+  image         String?
+
+  // Required when the Credentials provider is enabled.
+  // OAuth-only users won't have a password — keep it nullable.
+  password      String?
+
+  // Custom: optional role for (admin) gating.
+  role          String?   @default("user")
+
+  accounts      Account[]
+  sessions      Session[]
+
+  // Domain relations:
+  customers     Customer[]
+
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+}
+
+model Account {
+  id                String  @id @default(cuid())
+  userId            String
+  type              String
+  provider          String
+  providerAccountId String
+  refresh_token     String? @db.Text
+  access_token      String? @db.Text
+  expires_at        Int?
+  token_type        String?
+  scope             String?
+  id_token          String? @db.Text
+  session_state     String?
+
+  user              User    @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([provider, providerAccountId])
+  @@index([userId])
+}
+
+model Session {
+  // Present even when session.strategy = 'jwt' — the adapter still references it.
+  id           String   @id @default(cuid())
+  sessionToken String   @unique
+  userId       String
+  expires      DateTime
+
+  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+}
+
+model VerificationToken {
+  identifier String
+  token      String   @unique
+  expires    DateTime
+
+  @@unique([identifier, token])
+}
+
+// ---------- Domain models ----------
+
+model Customer {
+  id        String   @id @default(cuid())
+  userId    String
+  name      String
+  email     String
+
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId])
+}
+```
+
+## `prisma/seed.ts` (OPTIONAL — only if Credentials and a test user was requested)
+
+```ts
+import { PrismaClient } from '@prisma/client';
+import bcrypt from 'bcryptjs';
+
+const db = new PrismaClient();
+
+async function main() {
+  const password = await bcrypt.hash('test1234', 10);
+
+  await db.user.upsert({
+    where: { email: 'test@example.com' },
+    update: {},
+    create: {
+      email: 'test@example.com',
+      name: 'Test User',
+      password,
+      role: 'admin',
+    },
+  });
+
+  console.log('Seeded test@example.com / test1234');
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  })
+  .finally(() => db.$disconnect());
+```
+
+Run with `pnpm db:seed`. **Never seed production.**
+
+## Migration commands
+
+```bash
+# Dev (creates a new migration + applies it):
+pnpm exec prisma migrate dev --name init
+
+# CI / prod (applies committed migrations without prompting):
+pnpm exec prisma migrate deploy
+
+# Regenerate the typed client after a schema change (migrate dev does this for you):
+pnpm exec prisma generate
+
+# Inspect the DB visually (dev only):
+pnpm exec prisma studio
+```
+
+## Forbidden
+
+- `prisma db push` in CI or against any shared database. Use `prisma migrate dev` (development) or `prisma migrate deploy` (everything else).
+- Running `prisma migrate reset` without explicit user confirmation — it drops the DB.
+- Editing migration files after they've been applied to any non-throwaway database. Create a follow-up migration instead.
+- Adding domain tables that reference `Account` or `Session` directly. Those are NextAuth's tables; reference `User` instead.
+- Storing OAuth tokens or sensitive secrets in domain models — they belong in `Account` (which NextAuth populates).
+- Plain-text passwords. Always `bcrypt.hash(password, 10)` (or higher cost factor) before storing.

package/skills/nextjs-app-router/references/templates/providers-and-store.md

@@ -1,10 +1,11 @@
 # Providers, store, typed hooks
 
-## `src/redux/providers.tsx` (CLIENT — this one must be client because of `<Provider store>`)
+## `src/redux/providers.tsx` (CLIENT)
 
 ```tsx
 'use client';
 
+import { SessionProvider } from 'next-auth/react';
 import { Provider } from 'react-redux';
 import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';
 import { Toaster } from '@/components/ui/toaster';
@@ -12,39 +13,47 @@ import { store } from './store';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <Provider store={store}>
-      {children}
-      <Toaster />
-      <ProgressBar
-        height="3px"
-        color="hsl(var(--primary))"
-        shallowRouting
-        disableSameURL
-        options={{ showSpinner: false }}
-      />
-    </Provider>
+    <SessionProvider>
+      <Provider store={store}>
+        {children}
+        <Toaster />
+        <ProgressBar
+          height="3px"
+          color="hsl(var(--primary))"
+          shallowRouting
+          disableSameURL
+          options={{ showSpinner: false }}
+        />
+      </Provider>
+    </SessionProvider>
   );
 }
 ```
 
+**Order matters:** `<SessionProvider>` outside so any component (including Redux-connected ones) can `useSession()`. Redux inside so RTK Query and dispatches work normally.
+
 ## `src/redux/store.ts`
 
 ```ts
 import { combineReducers, configureStore, type Action } from '@reduxjs/toolkit';
 import { api } from './api/api';
-import { authApi } from './api/authApi';
-import { authSlice } from './features/authSlice';
 
 const combinedReducer = combineReducers({
   [api.reducerPath]: api.reducer,
-  auth: authSlice.reducer,
+  // Add additional slices here ONLY for genuinely shared async/global state.
+  // Auth/session is NOT a slice — it lives in NextAuth's SessionProvider.
 });
 
 type CombinedState = ReturnType<typeof combinedReducer>;
 
+const SIGN_OUT = '__signout__' as const;
+
+export const signOutEvent = { type: SIGN_OUT } as const;
+
 const rootReducer = (state: CombinedState | undefined, action: Action): CombinedState => {
-  // Wipe the entire store on logout. RTK Query cache, auth, everything.
-  if (authApi.endpoints.logout.matchFulfilled(action)) {
+  // Wipe the entire store when the app dispatches signOutEvent (called from the
+  // baseQuery 401 handler before invoking next-auth's signOut).
+  if (action.type === SIGN_OUT) {
     return combinedReducer(undefined, action);
   }
   return combinedReducer(state, action);
@@ -55,8 +64,7 @@ export const store = configureStore({
   middleware: (getDefaultMiddleware) =>
     getDefaultMiddleware({
       // Keep serializableCheck ON. If a specific value is genuinely non-serializable,
-      // add it here with a comment explaining why.
-      // serializableCheck: { ignoredPaths: ['auth.expiresAt'] },
+      // add { ignoredPaths: ['...'] } here with a comment explaining why.
     }).concat(api.middleware),
 });
 
@@ -64,7 +72,7 @@ export type RootState = ReturnType<typeof store.getState>;
 export type AppDispatch = typeof store.dispatch;
 ```
 
-**No `@ts-ignore`. No `serializableCheck: false`. No commented-out reducers.**
+**No `@ts-ignore`. No `serializableCheck: false`. No commented-out reducers. No auth slice — NextAuth owns session state.**
 
 ## `src/redux/hooks.ts`
 
@@ -76,4 +84,10 @@ export const useAppDispatch: () => AppDispatch = useDispatch;
 export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
 ```
 
-Components import `useAppDispatch` / `useAppSelector` — never the raw `useDispatch` / `useSelector` from `react-redux`. ESLint can enforce this with `no-restricted-imports` if desired.
+Components import `useAppDispatch` / `useAppSelector` — never the raw `useDispatch` / `useSelector` from `react-redux`. ESLint can enforce this with `no-restricted-imports`.
+
+## Why no `authSlice`
+
+NextAuth's `SessionProvider` is the single source of session truth. Components read it with `useSession()`. Duplicating that into a Redux slice creates two sources of truth that drift apart (the slice doesn't know when NextAuth refreshes the JWT, etc.) and doubles the work on sign-in/out.
+
+If you need session-derived data inside a Redux slice (rare — typically you'd put it in the request itself), select from `useSession()` at the component boundary and pass it as an action payload.

package/skills/nextjs-app-router/references/templates/root-layout.md

@@ -1,6 +1,6 @@
-# Root layout, root page, error/not-found templates
+# Root layout, error/not-found, login page
 
-## `src/app/layout.tsx` (SERVER component)
+## `src/app/layout.tsx` (SERVER component — the only one)
 
 ```tsx
 import '@/app/globals.css';
@@ -26,35 +26,51 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-**NO `'use client'`. NO `useEffect`. NO `useRouter`.** The root layout is a server component.
+**NO `'use client'`. NO data fetching. NO `await db.*`.** This is the only server component in the app and its job is to render `<Providers>`.
 
-## `src/app/page.tsx` (SERVER component, redirect-only)
+## No `src/app/page.tsx` by default
 
-If the project has an authenticated landing route, the root page is a server `redirect`:
+`middleware.ts` handles `/`:
+- Signed-in users → `/app/dashboard` (302).
+- Signed-out users → `/auth/login` (302).
+
+Don't create an `app/page.tsx` unless the project has a public landing page. If it does, the page is `'use client'`:
 
 ```tsx
-import { redirect } from 'next/navigation';
+// src/app/page.tsx — ONLY if a marketing landing is needed
+'use client';
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
 
-export default function Home() {
-  redirect('/dashboard');
+export default function LandingPage() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-6">
+      <h1 className="text-4xl font-bold">{{Project Title}}</h1>
+      <Button asChild>
+        <Link href="/auth/login">Sign in</Link>
+      </Button>
+    </main>
+  );
 }
 ```
 
-If the project has a marketing landing page, render content instead — still as a server component, no `'use client'`.
-
-**Forbidden:**
+**Forbidden** (do not generate):
 
 ```tsx
-// ❌ DO NOT generate this.
-'use client';
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-export default function Home() {
-  const router = useRouter();
-  useEffect(() => router.push('/dashboard'));
+// ❌ server page doing a redirect
+import { redirect } from 'next/navigation';
+export default function Home() { redirect('/dashboard'); }
+
+// ❌ server page doing data fetching
+export default async function Home() {
+  const session = await auth();
+  const data = await db.x.findMany();
+  return <Dashboard data={data} session={session} />;
 }
 ```
 
+The middleware handles redirects. RTK Query handles data.
+
 ## `src/app/error.tsx` (CLIENT — Next requires it)
 
 ```tsx
@@ -85,9 +101,11 @@ export default function GlobalError({
 }
 ```
 
-## `src/app/not-found.tsx` (SERVER component)
+## `src/app/not-found.tsx` (CLIENT, since no SSR)
 
 ```tsx
+'use client';
+
 import Link from 'next/link';
 import { Button } from '@/components/ui/button';
 
@@ -103,7 +121,68 @@ export default function NotFound() {
 }
 ```
 
-## `src/app/globals.css` (Tailwind layer + shadcn CSS variables)
+## `src/app/(public)/auth/login/page.tsx` (CLIENT, calls NextAuth `signIn`)
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { signIn } from 'next-auth/react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Form } from '@/components/ui/form';
+import { Button } from '@/components/ui/button';
+import { FormInputField } from '@/components/forms/FormInputField';
+import { FormPasswordField } from '@/components/forms/FormPasswordField';
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1, 'Required'),
+});
+
+type LoginFormValues = z.infer<typeof loginSchema>;
+
+export default function LoginPage() {
+  const router = useRouter();
+  const params = useSearchParams();
+  const returnTo = params.get('returnTo') ?? '/app/dashboard';
+  const [error, setError] = useState<string | null>(null);
+
+  const form = useForm<LoginFormValues>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: { email: '', password: '' },
+  });
+
+  const onSubmit = async (values: LoginFormValues) => {
+    setError(null);
+    const res = await signIn('credentials', { ...values, redirect: false });
+    if (res?.error) {
+      setError('Invalid email or password.');
+      return;
+    }
+    router.replace(returnTo);
+    router.refresh();
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <h1 className="text-xl font-semibold">Sign in</h1>
+        {error && <p className="text-sm text-destructive">{error}</p>}
+        <FormInputField form={form} schema={loginSchema} fieldName="email" label="Email" type="email" autoComplete="email" />
+        <FormPasswordField form={form} schema={loginSchema} fieldName="password" label="Password" autoComplete="current-password" />
+        <Button type="submit" className="w-full" disabled={form.formState.isSubmitting}>
+          {form.formState.isSubmitting ? 'Signing in…' : 'Sign in'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## `src/app/globals.css` (Tailwind + shadcn tokens)
 
 ```css
 @tailwind base;