@devmunna/agent-skillkit 0.1.0

package/skills/nextjs-fullstack/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: nextjs-fullstack
+version: 2.0.0
+description: >
+  Use this skill for any Next.js project task: App Router routing, Server Components, Client Components, Server Actions, Route Handlers, caching, auth, metadata, or deployment. Triggers: "Next.js App Router", "Server Component", "Server Action", "next/navigation", "layout.tsx", "page.tsx", "Route Handler", "next-auth", "Auth.js", "use cache", "after()", "PPR", "params Promise".
+stack: [nextjs, react, typescript, prisma]
+depends: []
+---
+
+# Next.js 15 — Full-Stack Production Skill
+
+**Version target:** Next.js 15 · React 19 · TypeScript 5 · Prisma v5 · Auth.js v5 (next-auth)
+
+---
+
+## Tech Stack
+
+| Layer | Package |
+|---|---|
+| Framework | next v15 |
+| UI | react v19 + react-dom v19 |
+| ORM | @prisma/client v5 |
+| Auth | next-auth v5 (Auth.js) |
+| Validation | zod v4 |
+| Styling | tailwindcss v4 |
+| Language | TypeScript 5 |
+
+---
+
+## App Router Folder Structure
+
+```
+src/
+├── app/
+│   ├── layout.tsx              # Root HTML shell (Server Component)
+│   ├── page.tsx                # Home page
+│   ├── loading.tsx             # Suspense fallback (auto-wrapped)
+│   ├── error.tsx               # Error boundary (must be 'use client')
+│   ├── not-found.tsx           # 404 page
+│   ├── globals.css
+│   ├── (auth)/                 # Route group — no URL segment
+│   │   ├── login/page.tsx
+│   │   └── register/page.tsx
+│   ├── (dashboard)/
+│   │   ├── layout.tsx          # Shared layout with sidebar
+│   │   ├── dashboard/page.tsx
+│   │   └── users/
+│   │       ├── page.tsx        # /users list
+│   │       ├── [id]/
+│   │       │   └── page.tsx    # /users/:id detail
+│   │       └── new/page.tsx    # /users/new create form
+│   └── api/
+│       └── {resource}/
+│           ├── route.ts        # GET /api/resource, POST /api/resource
+│           └── [id]/
+│               └── route.ts    # GET, PATCH, DELETE /api/resource/:id
+├── features/                   # Domain modules
+│   └── {feature}/
+│       ├── {feature}.actions.ts    # Server Actions ('use server')
+│       ├── {feature}.queries.ts    # DB query functions (Prisma calls)
+│       ├── {feature}.schema.ts     # Zod schemas + TypeScript types
+│       └── components/
+│           └── {Feature}Form.tsx   # Client form components
+├── components/
+│   ├── ui/                     # Shared primitive Client components
+│   └── server/                 # Server component compositions
+├── lib/
+│   ├── db.ts                   # Prisma singleton
+│   ├── auth.ts                 # Auth.js config
+│   └── session.ts              # Session helpers
+└── types/
+```
+
+---
+
+## Server vs Client Components
+
+**Default: Server Component.** Add `'use client'` ONLY when the component needs:
+- `useState`, `useEffect`, `useRef`, `useContext`
+- Browser APIs (`window`, `localStorage`, `document`)
+- Event handlers (`onClick`, `onChange`, `onSubmit`)
+- `useActionState`, `useOptimistic`, `useFormStatus` (React 19)
+- Third-party client-only libraries
+
+```tsx
+// app/(dashboard)/users/page.tsx — Server Component (no directive)
+import { db }       from '@/lib/db';
+import { UserList } from '@/features/users/components/UserList';
+
+export default async function UsersPage() {
+  const users = await db.user.findMany({
+    select: { id: true, name: true, email: true, role: true },
+    orderBy: { createdAt: 'desc' },
+  });
+  return <UserList users={users} />;
+}
+
+// features/users/components/DeleteButton.tsx — must be Client Component
+'use client';
+
+import { useTransition }    from 'react';
+import { deleteUserAction } from '../users.actions';
+
+export function DeleteButton({ userId }: { userId: string }) {
+  const [isPending, startTransition] = useTransition();
+
+  return (
+    <button
+      onClick={() => startTransition(() => deleteUserAction(userId))}
+      disabled={isPending}
+    >
+      {isPending ? 'Deleting...' : 'Delete'}
+    </button>
+  );
+}
+```
+
+---
+
+## Next.js 15 — Critical Changes
+
+### params is now a Promise in dynamic routes
+```tsx
+// Next.js 15 — params AND searchParams are Promises, must be awaited
+interface Props {
+  params:      Promise<{ id: string }>;
+  searchParams: Promise<{ page?: string }>;
+}
+
+export default async function UserPage({ params, searchParams }: Props) {
+  const { id }   = await params;
+  const { page } = await searchParams;
+
+  const user = await db.user.findUnique({ where: { id } });
+  if (!user) notFound();
+
+  return <UserDetail user={user} />;
+}
+```
+
+### `use cache` directive — function-level caching (Next.js 15)
+```ts
+// features/users/users.queries.ts
+'use cache';  // caches this module's exports
+
+import { cacheTag, cacheLife } from 'next/cache';
+import { db }                  from '@/lib/db';
+
+export async function getUsers() {
+  cacheTag('users');
+  cacheLife('hours');
+  return db.user.findMany({ orderBy: { createdAt: 'desc' } });
+}
+
+export async function getUserById(id: string) {
+  cacheTag('users', `user-${id}`);
+  cacheLife('minutes');
+  return db.user.findUnique({ where: { id } });
+}
+```
+
+On-demand invalidation (in Server Action or Route Handler):
+```ts
+import { revalidateTag } from 'next/cache';
+revalidateTag('users');          // invalidates all 'users' tagged cache
+revalidateTag(`user-${id}`);    // invalidate specific user cache
+```
+
+### `after()` — post-response side effects
+```ts
+import { after } from 'next/server';
+
+export async function createUserAction(formData: FormData) {
+  const user = await db.user.create({ data: /* ... */ });
+
+  // Runs AFTER response is sent — non-blocking, no delay to user
+  after(async () => {
+    await sendWelcomeEmail(user.email);
+    await createAuditLog('user.created', { userId: user.id });
+  });
+
+  revalidateTag('users');
+}
+```
+
+---
+
+## Server Actions
+
+Handle all mutations in Server Actions. Call from Client Components or HTML forms.
+
+```ts
+// features/users/users.actions.ts
+'use server';
+
+import { db }            from '@/lib/db';
+import { auth }          from '@/lib/auth';
+import { revalidateTag } from 'next/cache';
+import { redirect }      from 'next/navigation';
+import { createUserSchema } from './users.schema';
+
+export async function createUserAction(_prev: unknown, formData: FormData) {
+  const session = await auth();
+  if (!session) return { error: 'Unauthorized' };
+
+  const result = createUserSchema.safeParse({
+    name:  formData.get('name'),
+    email: formData.get('email'),
+  });
+
+  if (!result.success) {
+    return { error: result.error.issues[0].message };
+  }
+
+  try {
+    await db.user.create({ data: result.data });
+  } catch {
+    return { error: 'Failed to create user' };
+  }
+
+  revalidateTag('users');
+  redirect('/users');
+}
+
+export async function deleteUserAction(id: string) {
+  const session = await auth();
+  if (!session?.user || session.user.role !== 'ADMIN') {
+    throw new Error('Forbidden');
+  }
+
+  await db.user.delete({ where: { id } });
+  revalidateTag('users');
+  revalidateTag(`user-${id}`);
+}
+```
+
+Client form using `useActionState` (React 19):
+```tsx
+'use client';
+
+import { useActionState } from 'react';
+import { createUserAction } from '../users.actions';
+
+export function CreateUserForm() {
+  const [state, formAction, isPending] = useActionState(createUserAction, null);
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      {state?.error && <p className="error">{state.error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Error Handling
+
+```tsx
+// app/error.tsx — must be 'use client'
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+In Server Components: throw for unexpected errors, `notFound()` for 404s:
+```tsx
+import { notFound }   from 'next/navigation';
+
+if (!user) notFound();           // renders not-found.tsx
+if (!user) throw new Error('x'); // renders error.tsx
+```
+
+---
+
+## Metadata
+
+```tsx
+import type { Metadata } from 'next';
+
+// Static metadata
+export const metadata: Metadata = {
+  title: { template: '%s | My App', default: 'My App' },
+  description: 'App description',
+  openGraph: { type: 'website' },
+};
+
+// Dynamic metadata (Next.js 15 — params is a Promise)
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}): Promise<Metadata> {
+  const { id } = await params;
+  const user   = await db.user.findUnique({ where: { id } });
+  return { title: user?.name ?? 'User not found' };
+}
+```
+
+---
+
+## Core References
+
+| Topic | File |
+|---|---|
+| Server Components + data fetching patterns | `references/server-components.md` |
+| Server Actions + useActionState | `references/server-actions.md` |
+| Route Handlers (REST API) | `references/route-handlers.md` |
+| Caching — use cache, revalidate, tags | `references/caching.md` |
+| Auth.js v5 (next-auth) setup | `references/auth.md` |

package/skills/nextjs-fullstack/references/auth.md

@@ -0,0 +1,270 @@
+# Auth Reference — Auth.js v5 (next-auth)
+
+JWT-based session auth. `auth()` reads the session in Server Components, Server Actions, and Route Handlers.
+
+---
+
+## Installation
+
+```bash
+npm install next-auth@beta
+npx auth secret   # generates AUTH_SECRET in .env
+```
+
+---
+
+## lib/auth.ts — Configuration
+
+```ts
+// src/lib/auth.ts
+import NextAuth                  from 'next-auth';
+import CredentialsProvider       from 'next-auth/providers/credentials';
+import { PrismaAdapter }         from '@auth/prisma-adapter';
+import { db }                    from './db';
+import bcrypt                    from 'bcrypt';
+import { z }                     from 'zod';
+
+const loginSchema = z.object({
+  email:    z.string().email(),
+  password: z.string().min(1),
+});
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+  adapter: PrismaAdapter(db),
+
+  session: { strategy: 'jwt' },
+
+  pages: {
+    signIn: '/auth/login',
+  },
+
+  providers: [
+    CredentialsProvider({
+      async authorize(credentials) {
+        const parsed = loginSchema.safeParse(credentials);
+        if (!parsed.success) return null;
+
+        const user = await db.user.findUnique({
+          where: { email: parsed.data.email },
+        });
+        if (!user || !user.password) return null;
+
+        const valid = await bcrypt.compare(parsed.data.password, user.password);
+        if (!valid) return null;
+
+        return { id: user.id, name: user.name, email: user.email, role: user.role };
+      },
+    }),
+  ],
+
+  callbacks: {
+    // Add role to JWT
+    jwt({ token, user }) {
+      if (user) token.role = (user as any).role;
+      return token;
+    },
+    // Expose role in session
+    session({ session, token }) {
+      session.user.role = token.role as string;
+      return session;
+    },
+  },
+});
+```
+
+---
+
+## app/api/auth/[...nextauth]/route.ts
+
+```ts
+import { handlers } from '@/lib/auth';
+export const { GET, POST } = handlers;
+```
+
+---
+
+## .env
+
+```
+AUTH_SECRET=your-generated-secret-at-least-32-chars
+AUTH_URL=http://localhost:3000
+```
+
+---
+
+## TypeScript — Extend Session Types
+
+```ts
+// types/next-auth.d.ts
+import 'next-auth';
+import 'next-auth/jwt';
+
+declare module 'next-auth' {
+  interface Session {
+    user: { id: string; name: string; email: string; role: string };
+  }
+}
+
+declare module 'next-auth/jwt' {
+  interface JWT {
+    role: string;
+  }
+}
+```
+
+---
+
+## Usage — Server Components & Actions
+
+```ts
+// Reading session in Server Component / Action / Route Handler
+import { auth }     from '@/lib/auth';
+import { redirect } from 'next/navigation';
+
+// Server Component
+export default async function ProtectedPage() {
+  const session = await auth();
+  if (!session) redirect('/auth/login');
+
+  return <div>Hello {session.user.name}</div>;
+}
+
+// Server Action
+export async function sensitiveAction() {
+  const session = await auth();
+  if (!session)                          throw new Error('Unauthorized');
+  if (session.user.role !== 'ADMIN')     throw new Error('Forbidden');
+  // ... proceed
+}
+```
+
+---
+
+## Middleware — Route Protection
+
+```ts
+// middleware.ts (root of project, not inside src/)
+import { auth } from '@/lib/auth';
+import { NextResponse } from 'next/server';
+
+export default auth((req) => {
+  const isLoggedIn  = !!req.auth;
+  const isAuthRoute = req.nextUrl.pathname.startsWith('/auth');
+  const isApiRoute  = req.nextUrl.pathname.startsWith('/api');
+
+  if (isAuthRoute) {
+    if (isLoggedIn) return NextResponse.redirect(new URL('/dashboard', req.url));
+    return NextResponse.next();
+  }
+
+  if (!isLoggedIn && !isApiRoute) {
+    return NextResponse.redirect(new URL('/auth/login', req.url));
+  }
+
+  return NextResponse.next();
+});
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+---
+
+## Login Form (Client Component)
+
+```tsx
+// features/auth/components/LoginForm.tsx
+'use client';
+
+import { useActionState } from 'react';
+import { signIn }         from 'next-auth/react';
+import { useRouter }      from 'next/navigation';
+
+async function loginAction(_prev: any, formData: FormData) {
+  const result = await signIn('credentials', {
+    email:    formData.get('email'),
+    password: formData.get('password'),
+    redirect: false,
+  });
+
+  if (result?.error) return { error: 'Invalid email or password' };
+  return { success: true };
+}
+
+export function LoginForm() {
+  const router = useRouter();
+  const [state, formAction, isPending] = useActionState(loginAction, null);
+
+  if (state?.success) {
+    router.push('/dashboard');
+    return null;
+  }
+
+  return (
+    <form action={formAction}>
+      <input name="email"    type="email"    required placeholder="Email" />
+      <input name="password" type="password" required placeholder="Password" />
+      {state?.error && <p className="error">{state.error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Signing in...' : 'Sign in'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Prisma Schema for Auth.js
+
+```prisma
+model User {
+  id            String    @id @default(uuid())
+  name          String?
+  email         String    @unique
+  emailVerified DateTime?
+  image         String?
+  password      String?   // null for OAuth users
+  role          Role      @default(USER)
+  accounts      Account[]
+  sessions      Session[]
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+
+  @@map("users")
+}
+
+model Account {
+  id                String  @id @default(uuid())
+  userId            String
+  type              String
+  provider          String
+  providerAccountId String
+  refresh_token     String?
+  access_token      String?
+  expires_at        Int?
+  token_type        String?
+  scope             String?
+  id_token          String?
+  session_state     String?
+  user              User    @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([provider, providerAccountId])
+  @@index([userId])
+  @@map("accounts")
+}
+
+model Session {
+  id           String   @id @default(uuid())
+  sessionToken String   @unique
+  userId       String
+  expires      DateTime
+  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+  @@map("sessions")
+}
+
+enum Role { USER ADMIN MANAGER }
+```