@dennisrongo/skills 0.1.3 → 0.2.0

package/skills/nextjs-app-router/references/templates/route-group-layouts.md

@@ -1,8 +1,8 @@
 # Route group layouts
 
-Layouts are **server components** by default. Push interactive chrome into `'use client'` children.
+Group layouts are **server components** that render zero data — they just delegate to a `'use client'` shell. Pages inside the group are `'use client'`.
 
-## `src/app/(public)/layout.tsx` (SERVER)
+## `src/app/(public)/layout.tsx` (SERVER, zero data)
 
 ```tsx
 export default function PublicLayout({ children }: { children: React.ReactNode }) {
@@ -20,12 +20,14 @@ export default function PublicLayout({ children }: { children: React.ReactNode }
 import { AppShell } from './_components/AppShell';
 
 export default function AppLayout({ children }: { children: React.ReactNode }) {
-  // Server-side session check happens in middleware.ts.
-  // This layout assumes the request reached here because the user is authenticated.
+  // Server-side session check is done in middleware.ts — by the time we render here,
+  // the user is authenticated. We do NOT call `await auth()` here; the gate is the middleware.
   return <AppShell>{children}</AppShell>;
 }
 ```
 
+**No `await auth()` here.** The middleware already gated the request. Calling `auth()` again from this layout adds a round-trip and doesn't change the outcome.
+
 ## `src/app/(app)/_components/AppShell.tsx` (CLIENT, holds interactive UI state)
 
 ```tsx
@@ -50,9 +52,40 @@ export function AppShell({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## `src/app/(app)/loading.tsx` (SERVER)
+## `src/app/(app)/_components/UserMenu.tsx` (CLIENT — uses NextAuth)
 
 ```tsx
+'use client';
+
+import { signOut, useSession } from 'next-auth/react';
+import { Button } from '@/components/ui/button';
+
+export function UserMenu() {
+  const { data: session, status } = useSession();
+
+  if (status === 'loading') return null;
+  if (!session?.user) return null;
+
+  return (
+    <div className="flex items-center gap-3">
+      <span className="text-sm text-muted-foreground">{session.user.email}</span>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => signOut({ callbackUrl: '/auth/login', redirect: true })}
+      >
+        Sign out
+      </Button>
+    </div>
+  );
+}
+```
+
+## `src/app/(app)/loading.tsx` (CLIENT — Suspense fallback)
+
+```tsx
+'use client';
+
 export default function Loading() {
   return (
     <div className="flex h-[50vh] items-center justify-center">
@@ -87,4 +120,11 @@ export default function AppError({ error, reset }: { error: Error & { digest?: s
 
 ## `src/app/(admin)/layout.tsx` (OPTIONAL, SERVER)
 
-Same shape as `(app)/layout.tsx`. The role check happens in `middleware.ts`; this layout just renders an admin-flavored shell.
+Same shape as `(app)/layout.tsx`. The role check happens in `middleware.ts` (Variant B in [`middleware.md`](middleware.md)); this layout just renders an admin-flavored shell.
+
+## Forbidden in any layout
+
+- `await auth()` — duplicates middleware's job.
+- `await db.*` — server data fetching is banned.
+- `'use client'` directly on a `layout.tsx` — push interactive chrome into a client child.
+- `redirect()` — middleware handles all redirects.

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

@@ -0,0 +1,168 @@
+# Route Handler template
+
+Route Handlers under `src/app/api/**/route.ts` are the backend. Every one (except `/api/auth/[...nextauth]` and explicit public endpoints like `/api/health`) authenticates with `requireSession()`, validates inputs with the feature's Zod schema, and accesses the DB through the Prisma singleton.
+
+## `src/app/api/{{feature}}s/route.ts` — list + create
+
+```ts
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { requireSession, withApiErrors } from '@/lib/api-auth';
+import { {{feature}}Schema } from '@/app/(app)/{{feature}}s/schema';
+
+export const GET = withApiErrors(async () => {
+  const session = await requireSession();
+
+  const rows = await db.{{feature}}.findMany({
+    where: { userId: session.user.id },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return NextResponse.json(rows);
+});
+
+export const POST = withApiErrors(async (req: Request) => {
+  const session = await requireSession();
+
+  const body = await req.json().catch(() => null);
+  const parsed = {{feature}}Schema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
+  }
+
+  const created = await db.{{feature}}.create({
+    data: {
+      ...parsed.data,
+      userId: session.user.id,
+    },
+  });
+
+  return NextResponse.json(created, { status: 201 });
+});
+```
+
+## `src/app/api/{{feature}}s/[id]/route.ts` — get + update + delete
+
+```ts
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { requireSession, withApiErrors, assertOwnership } from '@/lib/api-auth';
+import { {{feature}}Schema } from '@/app/(app)/{{feature}}s/schema';
+
+interface RouteContext {
+  params: Promise<{ id: string }>;
+}
+
+export const GET = withApiErrors(async (_req: Request, ctx: RouteContext) => {
+  const session = await requireSession();
+  const { id } = await ctx.params;
+
+  const row = await db.{{feature}}.findFirst({
+    where: { id, userId: session.user.id },
+  });
+  if (!row) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+  return NextResponse.json(row);
+});
+
+export const PATCH = withApiErrors(async (req: Request, ctx: RouteContext) => {
+  const session = await requireSession();
+  const { id } = await ctx.params;
+
+  const body = await req.json().catch(() => null);
+  const parsed = {{feature}}Schema.partial().safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
+  }
+
+  // Ownership check via findFirst + userId predicate.
+  const existing = await db.{{feature}}.findFirst({
+    where: { id, userId: session.user.id },
+    select: { id: true },
+  });
+  if (!existing) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+  const updated = await db.{{feature}}.update({
+    where: { id },
+    data: parsed.data,
+  });
+
+  return NextResponse.json(updated);
+});
+
+export const DELETE = withApiErrors(async (_req: Request, ctx: RouteContext) => {
+  const session = await requireSession();
+  const { id } = await ctx.params;
+
+  const existing = await db.{{feature}}.findFirst({
+    where: { id, userId: session.user.id },
+    select: { id: true },
+  });
+  if (!existing) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+  await db.{{feature}}.delete({ where: { id } });
+
+  return new NextResponse(null, { status: 204 });
+});
+```
+
+## Public handlers (e.g. health check)
+
+The matcher in `middleware.ts` already excludes `/api/auth/*`. Other `/api/*` routes aren't redirected by middleware (they run their own `requireSession()`). A public handler simply omits the session check:
+
+```ts
+// src/app/api/health/route.ts
+import { NextResponse } from 'next/server';
+export const GET = () => NextResponse.json({ ok: true });
+```
+
+Comment in the file so the absence of `requireSession()` is intentional, not an oversight.
+
+## Forbidden
+
+- **No `requireSession()` call** in any handler outside `/api/auth/*` and explicitly-public ones (and the public ones must comment why).
+- **Trusting `userId` from the request body.** Always read it from the session: `session.user.id`.
+- **Returning the full record on POST/PATCH without checking ownership first** on updates — the `where: { id, userId }` predicate is the gate.
+- **`prisma.$queryRaw` with string concatenation.** Use parameterized template literals (`prisma.$queryRaw\`... ${value} ...\``) or stick to the typed query builder.
+- **Catching and re-throwing without logging.** `withApiErrors` logs unexpected errors; if you write your own try/catch, log unexpected ones at least once.
+- **Returning 500 with the raw error message.** Leaks stack traces. `withApiErrors` returns a generic message; if you write your own, do the same.
+- **Long-running work in a handler.** Route Handlers run per-request. For background work, dispatch to a queue (the skill doesn't ship one — ask the user to pick).
+- **`Set-Cookie` headers writing your own session cookie.** NextAuth owns the session cookie; setting a parallel one is the "custom JWT alongside NextAuth" anti-pattern.
+
+## Why we import the schema from the feature folder
+
+The form (`_components/{{Feature}}Form.tsx`) and the handler validate the same shape. If the handler had its own schema, drift would silently let the form post payloads the handler accepts but the form's UI hasn't accounted for — or vice versa. One Zod schema in `(app)/{{feature}}s/schema.ts` is the contract; both sides import it.
+
+## Handler test (optional but recommended)
+
+```ts
+// tests/unit/{{feature}}.handler.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/auth', () => ({ auth: vi.fn() }));
+vi.mock('@/lib/db', () => ({
+  db: { {{feature}}: { findMany: vi.fn(), create: vi.fn() } },
+}));
+
+import { GET, POST } from '@/app/api/{{feature}}s/route';
+import { auth } from '@/auth';
+import { db } from '@/lib/db';
+
+describe('GET /api/{{feature}}s', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('401s when unauthenticated', async () => {
+    (auth as ReturnType<typeof vi.fn>).mockResolvedValueOnce(null);
+    const res = await GET();
+    expect(res.status).toBe(401);
+  });
+
+  it('returns the current user's rows', async () => {
+    (auth as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ user: { id: 'u1' } });
+    (db.{{feature}}.findMany as ReturnType<typeof vi.fn>).mockResolvedValueOnce([{ id: 'r1', userId: 'u1' }]);
+    const res = await GET();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 'r1', userId: 'u1' }]);
+  });
+});
+```

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

@@ -1,6 +1,6 @@
 # Testing setup (Vitest + RTL + Playwright)
 
-A new project ships with three real tests: a reducer test, a component test, and an E2E auth spec. Three is enough to make CI meaningful; the user adds more as features grow.
+A new project ships with a small set of real tests: a Zod schema test, a Route Handler test, a component test, and an E2E auth spec. Just enough to make CI meaningful.
 
 ## `vitest.config.ts`
 
@@ -38,61 +38,123 @@ afterEach(() => {
 });
 ```
 
-## `tests/unit/auth.slice.test.ts`
+## `tests/unit/customer.schema.test.ts`
 
 ```ts
 import { describe, expect, it } from 'vitest';
-import { authSlice, logout, setUser } from '@/redux/features/authSlice';
+import { customerSchema } from '@/app/(app)/customers/schema';
 
-const initial = authSlice.getInitialState();
+describe('customerSchema', () => {
+  it('accepts a valid payload', () => {
+    expect(customerSchema.safeParse({ name: 'Acme', email: 'ops@acme.test' }).success).toBe(true);
+  });
+
+  it('rejects an empty name', () => {
+    expect(customerSchema.safeParse({ name: '', email: 'ops@acme.test' }).success).toBe(false);
+  });
+
+  it('rejects an invalid email', () => {
+    expect(customerSchema.safeParse({ name: 'Acme', email: 'nope' }).success).toBe(false);
+  });
+});
+```
+
+This is the test that pays for itself most often. The same schema validates form input *and* the Route Handler's request body, so regressions on either side fail here.
+
+## `tests/unit/customers.handler.test.ts` (Route Handler test with mocked `auth` + `db`)
+
+```ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/auth', () => ({ auth: vi.fn() }));
+vi.mock('@/lib/db', () => ({
+  db: {
+    customer: {
+      findMany: vi.fn(),
+      create: vi.fn(),
+    },
+  },
+}));
 
-describe('authSlice', () => {
-  it('starts logged out', () => {
-    expect(initial.user).toBeNull();
-    expect(initial.token).toBeNull();
+import { GET, POST } from '@/app/api/customers/route';
+import { auth } from '@/auth';
+import { db } from '@/lib/db';
+
+const mockAuth = auth as ReturnType<typeof vi.fn>;
+const mockFindMany = db.customer.findMany as ReturnType<typeof vi.fn>;
+const mockCreate = db.customer.create as ReturnType<typeof vi.fn>;
+
+describe('GET /api/customers', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('401s when unauthenticated', async () => {
+    mockAuth.mockResolvedValueOnce(null);
+    const res = await GET();
+    expect(res.status).toBe(401);
   });
 
-  it('sets the user', () => {
-    const state = authSlice.reducer(initial, setUser({ id: '1', email: 'a@b.c', name: 'A', roles: [] }));
-    expect(state.user?.id).toBe('1');
+  it('returns the current user\'s customers', async () => {
+    mockAuth.mockResolvedValueOnce({ user: { id: 'u1' } });
+    mockFindMany.mockResolvedValueOnce([{ id: 'c1', userId: 'u1', name: 'Acme' }]);
+    const res = await GET();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 'c1', userId: 'u1', name: 'Acme' }]);
   });
+});
 
-  it('logout resets state', () => {
-    const seeded = { ...initial, user: { id: '1', email: 'a@b.c', name: 'A', roles: [] } };
-    expect(authSlice.reducer(seeded, logout())).toEqual(initial);
+describe('POST /api/customers', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('400s on an invalid payload', async () => {
+    mockAuth.mockResolvedValueOnce({ user: { id: 'u1' } });
+    const req = new Request('http://x/api/customers', {
+      method: 'POST',
+      body: JSON.stringify({ name: '', email: 'nope' }),
+    });
+    const res = await POST(req);
+    expect(res.status).toBe(400);
+  });
+
+  it('attaches the session userId to the created row', async () => {
+    mockAuth.mockResolvedValueOnce({ user: { id: 'u1' } });
+    mockCreate.mockResolvedValueOnce({ id: 'c2', userId: 'u1', name: 'Acme', email: 'ops@acme.test' });
+    const req = new Request('http://x/api/customers', {
+      method: 'POST',
+      body: JSON.stringify({ name: 'Acme', email: 'ops@acme.test' }),
+    });
+    await POST(req);
+    expect(mockCreate).toHaveBeenCalledWith({
+      data: { name: 'Acme', email: 'ops@acme.test', userId: 'u1' },
+    });
   });
 });
 ```
 
+This test catches three common regressions: missing `requireSession`, body validation that silently accepts garbage, and userId tampering.
+
 ## `tests/unit/login-form.test.tsx`
 
 ```tsx
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { Provider } from 'react-redux';
-import { configureStore } from '@reduxjs/toolkit';
-import { api } from '@/redux/api/api';
-import { authSlice } from '@/redux/features/authSlice';
 import { LoginForm } from '@/app/(public)/auth/login/_components/LoginForm';
 
-function renderWithStore(ui: React.ReactElement) {
-  const store = configureStore({
-    reducer: { [api.reducerPath]: api.reducer, auth: authSlice.reducer },
-    middleware: (gdm) => gdm().concat(api.middleware),
-  });
-  return render(<Provider store={store}>{ui}</Provider>);
-}
+vi.mock('next-auth/react', () => ({
+  signIn: vi.fn().mockResolvedValue({ ok: true, error: null }),
+}));
 
 describe('<LoginForm />', () => {
-  it('shows a validation error for an empty email', async () => {
-    renderWithStore(<LoginForm />);
+  it('shows a validation error when fields are empty', async () => {
+    render(<LoginForm />);
     await userEvent.click(screen.getByRole('button', { name: /sign in/i }));
     expect(await screen.findByText(/required|invalid/i)).toBeInTheDocument();
   });
 });
 ```
 
+Mocking `next-auth/react` lets the form test run in isolation — we're testing the form, not NextAuth.
+
 ## `playwright.config.ts`
 
 ```ts
@@ -124,14 +186,26 @@ export default defineConfig({
 import { test, expect } from '@playwright/test';
 
 test('unauthenticated user is redirected to login', async ({ page }) => {
-  await page.goto('/dashboard');
+  await page.goto('/app/dashboard');
   await expect(page).toHaveURL(/\/auth\/login/);
   await expect(page.getByRole('heading', { name: /sign in/i })).toBeVisible();
 });
+
+// Requires `pnpm db:seed` to have run — provides test@example.com / test1234.
+test('seeded user can sign in and land on the dashboard', async ({ page }) => {
+  await page.goto('/auth/login');
+  await page.getByLabel(/email/i).fill('test@example.com');
+  await page.getByLabel(/password/i).fill('test1234');
+  await page.getByRole('button', { name: /sign in/i }).click();
+  await expect(page).toHaveURL(/\/app\/dashboard/);
+});
 ```
 
-That spec alone validates: middleware fires, the login page renders, the route group split works. If any of those regress, this test breaks.
+Together those two specs validate: middleware fires, the login page renders, NextAuth's Credentials provider works against the seeded user, and the route-group split holds.
 
 **Notes:**
-- Do not include Playwright in the default `pnpm test` script — keep it as `pnpm test:e2e` so CI can run Vitest fast and Playwright separately (or in a different job).
+
+- Do not include Playwright in the default `pnpm test` script — keep it as `pnpm test:e2e`.
+- The seed-then-login test requires the CI workflow's `pnpm db:seed` step (see [`ci-and-hooks.md`](ci-and-hooks.md)).
 - Real backend mocking (MSW) is *not* in the default scaffold. Add only if the user asks.
+- **Forbidden:** an `authSlice.test.ts`. There is no `authSlice` in this project — NextAuth owns session state. If you see a test importing `@/redux/features/authSlice`, delete it.