@dennisrongo/skills 0.1.3 → 0.2.0

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

@@ -1,95 +1,99 @@
-# Auth slice and auth API template
+# NextAuth integration (replaces the old auth slice)
 
-## `src/redux/features/authSlice.ts`
+There is **no `authSlice.ts`** in this project. NextAuth's `SessionProvider` is the single source of session truth. This file documents how the pieces fit together so nobody is tempted to reintroduce a redundant Redux slice.
 
-```ts
-import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
-import { authApi } from '@/redux/api/authApi';
-
-export interface AuthUser {
-  id: string;
-  email: string;
-  name: string;
-  roles: string[];
-}
+## Where session state lives
+
+| Need | Source |
+|------|--------|
+| "Is the user signed in?" (client) | `useSession()` from `next-auth/react` |
+| User id, email, role (client) | `useSession().data.user` |
+| Server-side session inside a Route Handler | `await auth()` (or `requireSession()`) |
+| Server-side session inside a server component (layouts only) | `await auth()` — **but layouts should not need this; middleware already gated** |
+| Sign-in trigger | `signIn('credentials', { email, password, redirect: false })` from `next-auth/react` |
+| Sign-out trigger | `signOut({ callbackUrl: '/auth/login', redirect: true })` |
+| Auth gate at the network boundary | `middleware.ts` |
+
+## Sign-in (Credentials provider)
+
+```tsx
+// src/app/(public)/auth/login/_components/LoginForm.tsx
+'use client';
 
-interface AuthState {
-  user: AuthUser | null;
-  token: string | null; // only populated for bearer-flow projects; null for httpOnly-cookie flows
-  expiresAt: number | null;
+import { signIn } from 'next-auth/react';
+import { useRouter, useSearchParams } from 'next/navigation';
+
+// inside onSubmit:
+const res = await signIn('credentials', { email, password, redirect: false });
+if (res?.error) {
+  // surface "Invalid email or password." — don't leak which field was wrong
+  return;
 }
+router.replace(searchParams.get('returnTo') ?? '/app/dashboard');
+router.refresh();
+```
 
-const initialState: AuthState = {
-  user: null,
-  token: null,
-  expiresAt: null,
-};
+## Sign-out
+
+```tsx
+'use client';
+import { signOut } from 'next-auth/react';
 
-export const authSlice = createSlice({
-  name: 'auth',
-  initialState,
-  reducers: {
-    logout: () => initialState,
-    setUser: (state, action: PayloadAction<AuthUser>) => {
-      state.user = action.payload;
-    },
-  },
-  extraReducers: (builder) => {
-    builder.addMatcher(authApi.endpoints.login.matchFulfilled, (state, { payload }) => {
-      state.user = payload.user;
-      state.token = payload.token ?? null;
-      state.expiresAt = payload.expiresAt ?? null;
-    });
-    builder.addMatcher(authApi.endpoints.getMe.matchFulfilled, (state, { payload }) => {
-      state.user = payload;
-    });
-  },
-});
-
-export const { logout, setUser } = authSlice.actions;
+<Button onClick={() => signOut({ callbackUrl: '/auth/login', redirect: true })}>
+  Sign out
+</Button>
 ```
 
-**Note:** the store's `rootReducer` already wipes the entire store on `authApi.endpoints.logout.matchFulfilled` — so a `logout()` action dispatched here from the 401 handler still triggers a full state reset via the wrapped reducer in `store.ts`. The slice's own `logout` reducer is there for cases where the user explicitly clicks "Sign out" without hitting the logout endpoint.
+The Redux store's `signOutEvent` is also dispatched from the RTK Query base on 401 (see [`api-base.md`](api-base.md)) to clear cached queries. For a user-initiated sign-out, that happens implicitly when the next request 401s — but if you want to clear the cache immediately on click, dispatch `signOutEvent` before calling `signOut`:
 
-## `src/redux/api/authApi.ts`
+```tsx
+import { useDispatch } from 'react-redux';
+import { signOutEvent } from '@/redux/store';
+
+const dispatch = useDispatch();
+const onSignOut = () => {
+  dispatch(signOutEvent);
+  void signOut({ callbackUrl: '/auth/login', redirect: true });
+};
+```
+
+## Module augmentation — `src/types/next-auth.d.ts`
+
+Without this, `session.user.id` is `undefined` in TypeScript even though the runtime callback puts it there.
 
 ```ts
-import { api } from './api';
-import type { AuthUser } from '@/redux/features/authSlice';
+import 'next-auth';
+import 'next-auth/jwt';
 
-export interface LoginRequest {
-  email: string;
-  password: string;
-}
+declare module 'next-auth' {
+  interface Session {
+    user: {
+      id: string;
+      email: string;
+      name?: string | null;
+      image?: string | null;
+      role?: string;
+    };
+  }
 
-export interface LoginResponse {
-  user: AuthUser;
-  /** Populated only for bearer-token flows. httpOnly-cookie flows leave this undefined. */
-  token?: string;
-  expiresAt?: number;
+  interface User {
+    id: string;
+    role?: string;
+  }
 }
 
-export const authApi = api.injectEndpoints({
-  endpoints: (build) => ({
-    login: build.mutation<LoginResponse, LoginRequest>({
-      query: (body) => ({ url: '/auth/login', method: 'POST', body }),
-      invalidatesTags: ['Auth'],
-    }),
-    logout: build.mutation<void, void>({
-      query: () => ({ url: '/auth/logout', method: 'POST' }),
-      invalidatesTags: ['Auth'],
-    }),
-    getMe: build.query<AuthUser, void>({
-      query: () => '/auth/me',
-      providesTags: ['Auth'],
-    }),
-  }),
-});
-
-export const { useLoginMutation, useLogoutMutation, useGetMeQuery } = authApi;
+declare module 'next-auth/jwt' {
+  interface JWT {
+    id: string;
+    role?: string;
+  }
+}
 ```
 
-**Forbidden:**
-- Storing the token via `js-cookie` inside the slice (`Cookies.set('token', ...)`). For `httpOnly` flows, the backend sets the cookie; for bearer flows, the token lives in Redux state and the `prepareHeaders` callback attaches it. Never both.
-- Base64-encoding the user and writing it to a cookie (`Cookies.set('user', btoa(JSON.stringify(...)))`). It's not encryption, it's obfuscation. If the server needs the user, the server reads it from the session cookie / database.
-- Decoding the JWT on the client to drive auth decisions. Decode only for non-sensitive display (e.g. showing the user's name pulled from a claim) — never as the gate. The gate is the server.
+## Forbidden
+
+- A Redux `authSlice` storing `user`, `token`, or `expiresAt`. Use `useSession()`.
+- Manual `js-cookie` writes (`Cookies.set('token', ...)`). NextAuth owns the session cookie and it's `httpOnly` by design.
+- Decoding the NextAuth JWT on the client. Use the hook.
+- Calling `await auth()` inside a server `layout.tsx` "just to check". Middleware already gated. Calling `auth()` again is a round-trip with no behavior change.
+- A second auth library (`Clerk`, `Lucia`, custom JWT signer) running alongside NextAuth.

package/skills/nextjs-app-router/references/templates/ci-and-hooks.md

@@ -18,6 +18,27 @@ jobs:
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: {{project_db}}_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/{{project_db}}_test
+      AUTH_SECRET: ci-only-secret-replace-in-prod-1234567890abcdef
+      AUTH_URL: http://localhost:3000
+
     steps:
       - uses: actions/checkout@v4
 
@@ -32,12 +53,14 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
+      # Apply committed migrations against the CI Postgres. Never `prisma db push` here.
+      - run: pnpm exec prisma migrate deploy
+      - run: pnpm exec prisma generate
+
       - run: pnpm lint --max-warnings=0
       - run: pnpm typecheck
       - run: pnpm test
       - run: pnpm build
-        env:
-          NEXT_PUBLIC_API_BASE_URL: http://localhost:5000
 
   # Optional separate job for E2E — only run on push to main to save CI minutes.
   e2e:
@@ -45,6 +68,27 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     needs: build
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: {{project_db}}_e2e
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/{{project_db}}_e2e
+      AUTH_SECRET: ci-only-secret-replace-in-prod-1234567890abcdef
+      AUTH_URL: http://localhost:3000
+
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -52,16 +96,22 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 20, cache: pnpm }
       - run: pnpm install --frozen-lockfile
+      - run: pnpm exec prisma migrate deploy
+      - run: pnpm exec prisma generate
+      - run: pnpm db:seed
       - run: pnpm exec playwright install --with-deps chromium
       - run: pnpm test:e2e
-        env:
-          NEXT_PUBLIC_API_BASE_URL: http://localhost:5000
 ```
 
 **Notes:**
+
 - `--frozen-lockfile` ensures the lockfile is honored — CI fails if `package.json` and lockfile drift.
 - `--max-warnings=0` on lint means even warnings fail CI. On a fresh scaffold there are none; this catches regressions early.
-- E2E is split into its own job behind `if: github.event_name == 'push'` so PRs stay fast.
+- `AUTH_SECRET` in CI is a throwaway. **Do not** reuse it in production. The placeholder above is long enough to satisfy the `z.string().min(32)` check in `src/config/env.ts`.
+- `prisma migrate deploy` applies committed migrations. **Never** `prisma db push` in CI — it bypasses the migration history.
+- `prisma generate` runs after `migrate deploy` so `@prisma/client` matches the schema. (`migrate deploy` does not regenerate the client; `migrate dev` does, but `migrate dev` is interactive and not for CI.)
+- The E2E job seeds a test user via `pnpm db:seed` so the Credentials login flow has something to authenticate against.
+- E2E is gated on `github.event_name == 'push'` so PRs stay fast.
 
 ## Husky + lint-staged
 
@@ -85,10 +135,12 @@ The `lint-staged` config lives in `package.json` (see [`package.md`](package.md)
 ```jsonc
 "lint-staged": {
   "*.{ts,tsx}": ["prettier --write", "eslint --fix"],
-  "*.{json,md,css,yml,yaml}": ["prettier --write"]
+  "*.{json,md,css,yml,yaml,prisma}": ["prettier --write"]
 }
 ```
 
 **Notes:**
+
 - Do not put `tsc --noEmit` in lint-staged — it's per-staged-file and TypeScript is project-wide; let CI handle it.
 - Do not skip hooks (`--no-verify`) as a workflow. If a hook is annoying, fix the underlying issue.
+- `prettier-plugin-prisma` (auto-loaded when present in deps) formats `schema.prisma` on commit.

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

@@ -0,0 +1,48 @@
+# Prisma client (singleton)
+
+## `src/lib/db.ts`
+
+```ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+
+export const db =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = db;
+}
+```
+
+## Why a singleton
+
+Next.js dev hot-reload re-evaluates modules on every change. Without the global cache, each reload constructs a fresh `PrismaClient`, opens a new connection pool, and never closes the old one — within minutes of editing you exhaust your Postgres `max_connections` and start seeing `FATAL: sorry, too many clients already`.
+
+The pattern above:
+- In **production**, behaves like a normal module-scoped singleton (one client per process).
+- In **dev**, attaches the client to `globalThis` so hot-reloads reuse it.
+
+## Forbidden
+
+- `import { PrismaClient } from '@prisma/client'; const prisma = new PrismaClient()` anywhere outside this file. Every consumer imports `db` from `@/lib/db`.
+- Importing `db` from `src/auth.config.ts` (Edge runtime — can't import Prisma).
+- Importing `db` from any `src/app/**` file outside `route.ts` files. Server pages and layouts do not touch the database.
+- Calling `db.$connect()` / `db.$disconnect()` manually in handlers. Prisma manages the pool. The only place a manual `$disconnect()` is appropriate is at the bottom of `prisma/seed.ts`.
+
+## Where `db` is allowed to be imported
+
+| File pattern | Allowed? |
+|---|---|
+| `src/app/api/**/route.ts` | ✅ Yes |
+| `src/auth.ts` | ✅ Yes (Credentials `authorize` reads user table) |
+| `prisma/seed.ts` | ✅ Yes (uses `new PrismaClient()` directly; doesn't share with the app) |
+| `src/lib/*.ts` (server-only helpers) | ✅ Yes |
+| `src/auth.config.ts` | ❌ No — Edge runtime |
+| `middleware.ts` | ❌ No — Edge runtime |
+| `src/app/**/page.tsx` / `layout.tsx` (any non-`route.ts`) | ❌ No — pages/layouts don't fetch data; RTK Query → /api → db |
+| `src/redux/**` | ❌ No — Redux runs in the browser |
+| `src/components/**` | ❌ No |

package/skills/nextjs-app-router/references/templates/env-and-utils.md

@@ -1,4 +1,4 @@
-# Env validation, `cn()`, and shared utils
+# Env validation, `cn()`, shared utils
 
 ## `src/config/env.ts` (runtime-validated env)
 
@@ -6,16 +6,23 @@
 import { z } from 'zod';
 
 const envSchema = z.object({
-  NEXT_PUBLIC_API_BASE_URL: z.string().url(),
-  // Add more vars here as needed. Keep client-readable ones prefixed with NEXT_PUBLIC_.
+  // NextAuth — required.
+  AUTH_SECRET: z.string().min(32, 'AUTH_SECRET must be at least 32 chars. Generate with: openssl rand -base64 32'),
+  AUTH_URL: z.string().url().optional(), // required in prod, derived locally
+
+  // Database — required.
+  DATABASE_URL: z.string().url(),
+
+  // OAuth providers — required ONLY if the matching provider is enabled in auth.config.ts.
+  AUTH_GITHUB_ID: z.string().optional(),
+  AUTH_GITHUB_SECRET: z.string().optional(),
+  AUTH_GOOGLE_ID: z.string().optional(),
+  AUTH_GOOGLE_SECRET: z.string().optional(),
 });
 
 function loadEnv() {
-  const parsed = envSchema.safeParse({
-    NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,
-  });
+  const parsed = envSchema.safeParse(process.env);
   if (!parsed.success) {
-    // Fail fast at module load.
     console.error('Invalid environment configuration:', parsed.error.flatten().fieldErrors);
     throw new Error('Invalid environment configuration. See .env.example for required variables.');
   }
@@ -25,23 +32,31 @@ function loadEnv() {
 export const env = loadEnv();
 ```
 
-**Why:** misconfiguration (`NEXT_PUBLIC_API_BASE_URL` undefined, typo'd) blows up at startup with a clear error, not via a confusing 404 on the first network request.
+**Why:** misconfiguration (missing `AUTH_SECRET`, malformed `DATABASE_URL`) blows up at startup with a clear error, not via a confusing 500 on the first auth check or DB query.
 
-## `.env.example` (committed)
+## `.env.example` (committed — NO secret values)
 
-```
-# Backend API base URL. Required.
-NEXT_PUBLIC_API_BASE_URL=http://localhost:5000
+```dotenv
+# ---- NextAuth ----
+# Generate with: openssl rand -base64 32  (or `npx auth secret`)
+# REQUIRED. Do NOT commit a real value.
+AUTH_SECRET=
+
+# Public URL of the app. Required in production. Optional locally (Auth.js derives from the request).
+# AUTH_URL=https://example.com
 
-# Optional: real-time
-# NEXT_PUBLIC_PUSHER_KEY=
-# NEXT_PUBLIC_PUSHER_CLUSTER=
+# ---- Database ----
+# Required. For local Docker: postgresql://postgres:postgres@localhost:5432/{{project_db}}
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/{{project_db}}
 
-# Server-only: JWT verification key (only for Variant B middleware).
-# JWT_VERIFY_KEY=
+# ---- OAuth providers (only if enabled in src/auth.config.ts) ----
+# AUTH_GITHUB_ID=
+# AUTH_GITHUB_SECRET=
+# AUTH_GOOGLE_ID=
+# AUTH_GOOGLE_SECRET=
 ```
 
-`.env`, `.env.local`, `.env.*.local` go in `.gitignore`. Only `.env.example` is committed.
+`.env`, `.env.local`, `.env.*.local` go in `.gitignore`. Only `.env.example` is committed. **`AUTH_SECRET` must never have a real value in `.env.example`** — leave it empty with a comment showing how to generate one.
 
 ## `src/lib/utils.ts`
 
@@ -56,6 +71,61 @@ export function cn(...inputs: ClassValue[]): string {
 
 That's the entire file. No bag of unrelated helpers — those go in `src/lib/formatters/` or feature-local utility files.
 
+## `src/lib/api-auth.ts` (Route Handler auth helper)
+
+```ts
+import { NextResponse } from 'next/server';
+import { auth } from '@/auth';
+
+export class HttpError extends Error {
+  constructor(public status: number, public body: unknown) {
+    super(typeof body === 'string' ? body : JSON.stringify(body));
+  }
+}
+
+/**
+ * Returns the current session, or throws an HttpError(401) that the wrapping
+ * handler converts to a 401 JSON response. Use inside Route Handlers.
+ */
+export async function requireSession() {
+  const session = await auth();
+  if (!session?.user?.id) {
+    throw new HttpError(401, { error: 'Unauthorized' });
+  }
+  return session as typeof session & { user: { id: string; email: string; role?: string } };
+}
+
+/**
+ * Wraps a Route Handler so that thrown HttpErrors become JSON responses.
+ * Optional — handlers can also try/catch themselves.
+ */
+export function withApiErrors<T extends (...args: never[]) => Promise<Response | NextResponse>>(
+  fn: T,
+): T {
+  return (async (...args: Parameters<T>) => {
+    try {
+      return await fn(...args);
+    } catch (err) {
+      if (err instanceof HttpError) {
+        return NextResponse.json(err.body, { status: err.status });
+      }
+      console.error('Unhandled handler error:', err);
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+    }
+  }) as T;
+}
+
+/**
+ * Asserts that a fetched row belongs to the current user. Returns the row.
+ */
+export function assertOwnership<T extends { userId: string }>(row: T | null, userId: string): T {
+  if (!row || row.userId !== userId) {
+    throw new HttpError(404, { error: 'Not found' });
+  }
+  return row;
+}
+```
+
 ## `src/lib/formatters/date.ts`
 
 ```ts
@@ -99,12 +169,9 @@ export function UnsavedChangesWarning({ when, message = 'You have unsaved change
     return () => window.removeEventListener('beforeunload', onBeforeUnload);
   }, [when, message]);
 
-  // Next's App Router does not yet expose a stable router-events API for intercepting client-side navigation.
-  // The pattern below (overriding history.pushState) is a workaround — review and adjust per the Next version
-  // resolved at scaffold time (use context7 to check whether the official `useBeforeUnload` / `unstable_*` API has landed).
+  // Next App Router does not yet expose a stable router-events API for intercepting client-side navigation.
+  // Verify at scaffold time via context7 whether a stable hook has landed; if so, use it here in addition to beforeunload.
 
   return null;
 }
 ```
-
-**Adjust at scaffold time:** if the Next.js version resolved in Step 1 exposes a stable navigation-intercept hook, use it instead of the `beforeunload`-only fallback. Verify via context7.