@devmunna/agent-skillkit 0.1.0

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

@@ -0,0 +1,157 @@
+# Caching Reference — Next.js 15
+
+---
+
+## Caching Layers (top to bottom)
+
+| Layer | Scope | How to control |
+|---|---|---|
+| `use cache` | Function / module level | `cacheTag()`, `cacheLife()` |
+| `fetch()` cache | Individual fetch calls | `cache`, `next.revalidate`, `next.tags` |
+| Page-level | Full page / layout | `export const revalidate`, `export const dynamic` |
+| On-demand | After mutations | `revalidateTag()`, `revalidatePath()` |
+
+---
+
+## `use cache` Directive (Next.js 15) — Preferred
+
+Tag cached functions for on-demand invalidation:
+
+```ts
+// features/users/users.queries.ts
+'use cache';
+
+import { cacheTag, cacheLife } from 'next/cache';
+import { db }                  from '@/lib/db';
+
+// Cache entire user list, invalidate with 'users' tag
+export async function getUsers() {
+  cacheTag('users');
+  cacheLife('hours');   // seconds | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'max'
+  return db.user.findMany({ orderBy: { createdAt: 'desc' } });
+}
+
+// Per-record cache
+export async function getUserById(id: string) {
+  cacheTag('users', `user-${id}`);
+  cacheLife('minutes');
+  return db.user.findUnique({
+    where:  { id },
+    select: { id: true, name: true, email: true, role: true },
+  });
+}
+```
+
+Invalidate from a Server Action or Route Handler:
+```ts
+import { revalidateTag } from 'next/cache';
+
+revalidateTag('users');          // all list caches
+revalidateTag(`user-${id}`);    // specific record cache
+```
+
+---
+
+## Page-Level Caching
+
+```tsx
+// Revalidate the whole page every 60 seconds (ISR)
+export const revalidate = 60;
+
+// Always render fresh — opt out of caching entirely
+export const dynamic = 'force-dynamic';
+
+// Static generation only — never dynamic
+export const dynamic = 'force-static';
+```
+
+---
+
+## fetch() Caching
+
+```ts
+// Revalidate every 30 seconds + tag for on-demand invalidation
+const res = await fetch('/api/data', {
+  next: { revalidate: 30, tags: ['data'] },
+});
+
+// Never cache
+const res = await fetch('/api/live', { cache: 'no-store' });
+
+// Cache indefinitely until manually revalidated
+const res = await fetch('/api/config', { cache: 'force-cache' });
+```
+
+---
+
+## On-Demand Revalidation
+
+```ts
+// In Server Action or Route Handler — called after mutations
+import { revalidateTag, revalidatePath } from 'next/cache';
+
+// Prefer revalidateTag (more precise, works with use cache)
+revalidateTag('users');
+revalidateTag(`user-${id}`);
+
+// revalidatePath — revalidates all data for a given URL
+revalidatePath('/users');
+revalidatePath('/users/[id]', 'page');   // all dynamic [id] pages
+```
+
+---
+
+## `after()` — Non-Blocking Post-Response Work
+
+Run side effects (emails, analytics, audit logs) after the response is sent to the user:
+
+```ts
+import { after } from 'next/server';
+
+export async function createUserAction(formData: FormData) {
+  const user = await db.user.create({ /* ... */ });
+
+  // These run AFTER the redirect/response — user doesn't wait
+  after(async () => {
+    await sendWelcomeEmail(user.email);
+    await logAuditEvent('user.created', { userId: user.id });
+  });
+
+  revalidateTag('users');
+}
+```
+
+---
+
+## unstable_cache (legacy — prefer `use cache`)
+
+```ts
+import { unstable_cache } from 'next/cache';
+
+// Still works in Next.js 15 but use cache directive is preferred
+const getCachedUsers = unstable_cache(
+  async () => db.user.findMany(),
+  ['users-list'],
+  { revalidate: 3600, tags: ['users'] },
+);
+```
+
+---
+
+## Common Patterns
+
+```ts
+// Static data — config, reference lists (cache forever)
+cacheLife('max');
+
+// User content — pages, posts (cache for hours)
+cacheLife('hours');
+
+// Dashboard stats (cache for minutes)
+cacheLife('minutes');
+
+// Live data — prices, inventory (no cache)
+export const dynamic = 'force-dynamic';
+// or
+const data = await fetch(url, { cache: 'no-store' });
+```

package/skills/nextjs-fullstack/references/route-handlers.md

@@ -0,0 +1,194 @@
+# Route Handlers Reference
+
+Use Route Handlers for: public REST APIs consumed by external clients, file uploads, webhooks from third parties, or complex streaming responses. For internal Next.js mutations, prefer Server Actions.
+
+---
+
+## File Conventions
+
+```
+app/api/
+├── users/
+│   ├── route.ts          # GET /api/users, POST /api/users
+│   └── [id]/
+│       └── route.ts      # GET, PATCH, DELETE /api/users/:id
+└── webhooks/
+    └── stripe/
+        └── route.ts      # POST /api/webhooks/stripe
+```
+
+---
+
+## Collection Route — route.ts
+
+```ts
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db }   from '@/lib/db';
+import { auth } from '@/lib/auth';
+import { z }    from 'zod';
+
+const listSchema = z.object({
+  page:   z.coerce.number().int().positive().default(1),
+  limit:  z.coerce.number().int().positive().max(100).default(10),
+  search: z.string().optional(),
+});
+
+const createSchema = z.object({
+  name:  z.string().min(2),
+  email: z.string().email(),
+  role:  z.enum(['USER', 'ADMIN', 'MANAGER']).default('USER'),
+});
+
+export async function GET(req: NextRequest) {
+  const session = await auth();
+  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const { searchParams } = req.nextUrl;
+  const parsed = listSchema.safeParse(Object.fromEntries(searchParams));
+
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.issues[0].message },
+      { status: 422 },
+    );
+  }
+
+  const { page, limit, search } = parsed.data;
+  const skip  = (page - 1) * limit;
+  const where = search ? { name: { contains: search, mode: 'insensitive' as const } } : {};
+
+  const [data, total] = await Promise.all([
+    db.user.findMany({ where, skip, take: limit, orderBy: { createdAt: 'desc' } }),
+    db.user.count({ where }),
+  ]);
+
+  return NextResponse.json({
+    data,
+    meta: { total, page, limit, totalPages: Math.ceil(total / limit) },
+  });
+}
+
+export async function POST(req: NextRequest) {
+  const session = await auth();
+  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const body   = await req.json();
+  const parsed = createSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.issues[0].message },
+      { status: 422 },
+    );
+  }
+
+  try {
+    const user = await db.user.create({ data: parsed.data });
+    return NextResponse.json(user, { status: 201 });
+  } catch (err: any) {
+    if (err.code === 'P2002') {
+      return NextResponse.json({ error: 'Email already registered' }, { status: 409 });
+    }
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+  }
+}
+```
+
+---
+
+## Item Route — [id]/route.ts
+
+```ts
+// app/api/users/[id]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db }   from '@/lib/db';
+import { auth } from '@/lib/auth';
+import { z }    from 'zod';
+
+interface Ctx { params: Promise<{ id: string }> }   // Next.js 15 — params is a Promise
+
+const updateSchema = z.object({
+  name:  z.string().min(2).optional(),
+  email: z.string().email().optional(),
+}).strict();
+
+export async function GET(_req: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  const user   = await db.user.findUnique({ where: { id } });
+  if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  return NextResponse.json(user);
+}
+
+export async function PATCH(req: NextRequest, { params }: Ctx) {
+  const session = await auth();
+  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const { id } = await params;
+  const body   = await req.json();
+  const parsed = updateSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.issues[0].message }, { status: 422 });
+  }
+
+  const user = await db.user.update({ where: { id }, data: parsed.data });
+  return NextResponse.json(user);
+}
+
+export async function DELETE(_req: NextRequest, { params }: Ctx) {
+  const session = await auth();
+  if (!session?.user || session.user.role !== 'ADMIN') {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
+  const { id } = await params;
+  await db.user.delete({ where: { id } });
+  return new NextResponse(null, { status: 204 });
+}
+```
+
+---
+
+## Webhook Route (raw body, no auth middleware)
+
+```ts
+// app/api/webhooks/stripe/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export async function POST(req: NextRequest) {
+  const body      = await req.text();
+  const signature = req.headers.get('stripe-signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  switch (event.type) {
+    case 'payment_intent.succeeded':
+      // handle payment
+      break;
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+---
+
+## Response Helpers
+
+```ts
+// Consistent JSON responses
+return NextResponse.json(data);                              // 200
+return NextResponse.json(data, { status: 201 });            // 201
+return NextResponse.json({ error: 'msg' }, { status: 400 }); // 400
+return new NextResponse(null, { status: 204 });              // 204 no content
+return NextResponse.redirect(new URL('/login', req.url));   // redirect
+```

package/skills/nextjs-fullstack/references/server-actions.md

@@ -0,0 +1,214 @@
+# Server Actions Reference
+
+Server Actions run on the server. They can be called from Client Components via `action=` prop or event handlers. No separate API route needed for simple mutations.
+
+---
+
+## Action File Pattern — {feature}.actions.ts
+
+```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 { after }         from 'next/server';
+import { createUserSchema, updateUserSchema } from './users.schema';
+
+// Create — returns state object for useActionState
+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'),
+    role:  formData.get('role'),
+  });
+
+  if (!result.success) {
+    return { error: result.error.issues[0].message };
+  }
+
+  try {
+    const user = await db.user.create({ data: result.data });
+    after(() => sendWelcomeEmail(user.email));  // fire-and-forget after response
+  } catch (err: any) {
+    if (err.code === 'P2002') return { error: 'Email already registered' };
+    return { error: 'Failed to create user' };
+  }
+
+  revalidateTag('users');
+  redirect('/users');
+}
+
+// Update — accepts structured args (not FormData)
+export async function updateUserAction(id: string, data: { name?: string; email?: string }) {
+  const session = await auth();
+  if (!session) throw new Error('Unauthorized');
+
+  const result = updateUserSchema.safeParse(data);
+  if (!result.success) throw new Error(result.error.issues[0].message);
+
+  await db.user.update({ where: { id }, data: result.data });
+
+  revalidateTag('users');
+  revalidateTag(`user-${id}`);
+}
+
+// Delete — called from event handler in Client Component
+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 — useActionState (React 19)
+
+`useActionState` is the primary way to wire a Server Action to a form with pending + error state:
+
+```tsx
+// features/users/components/CreateUserForm.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}>
+      <div>
+        <label>Name</label>
+        <input name="name" required />
+      </div>
+      <div>
+        <label>Email</label>
+        <input name="email" type="email" required />
+      </div>
+      <select name="role" defaultValue="USER">
+        <option value="USER">User</option>
+        <option value="ADMIN">Admin</option>
+      </select>
+
+      {state?.error && <p className="error">{state.error}</p>}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## useOptimistic — Optimistic Updates
+
+```tsx
+'use client';
+
+import { useOptimistic, useTransition } from 'react';
+import { deleteUserAction }             from '../users.actions';
+import type { User }                    from '../users.schema';
+
+export function UserList({ users }: { users: User[] }) {
+  const [optimisticUsers, removeOptimistic] = useOptimistic(
+    users,
+    (state, removedId: string) => state.filter((u) => u.id !== removedId),
+  );
+  const [isPending, startTransition] = useTransition();
+
+  const handleDelete = (id: string) => {
+    startTransition(async () => {
+      removeOptimistic(id);           // instant UI update
+      await deleteUserAction(id);     // real delete on server
+    });
+  };
+
+  return (
+    <ul>
+      {optimisticUsers.map((user) => (
+        <li key={user.id}>
+          {user.name}
+          <button onClick={() => handleDelete(user.id)} disabled={isPending}>
+            Delete
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Calling Actions from Event Handlers
+
+Actions can also be called directly (not through a form `action=`):
+
+```tsx
+'use client';
+
+import { useTransition } from 'react';
+import { updateUserAction } from '../users.actions';
+
+export function StatusToggle({ user }: { user: User }) {
+  const [isPending, startTransition] = useTransition();
+
+  const toggle = () => {
+    startTransition(async () => {
+      await updateUserAction(user.id, { active: !user.active });
+    });
+  };
+
+  return (
+    <button onClick={toggle} disabled={isPending}>
+      {user.active ? 'Deactivate' : 'Activate'}
+    </button>
+  );
+}
+```
+
+---
+
+## useFormStatus — Pending State in Child Components
+
+```tsx
+'use client';
+
+import { useFormStatus } from 'react-dom';
+
+// Reads pending state from the nearest parent <form>
+export function SubmitButton({ label }: { label: string }) {
+  const { pending } = useFormStatus();
+
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Saving...' : label}
+    </button>
+  );
+}
+```
+
+---
+
+## Rules
+
+- Always authenticate at the top of every Server Action — never trust the caller
+- Return `{ error: string }` from `useActionState` actions (never throw — it breaks the state pattern)
+- Throw from actions called via `startTransition` — error boundary catches it
+- Use `revalidateTag` after mutations, never `revalidatePath` for cacheable data
+- Use `after()` for non-critical side effects (emails, logs) — keeps the action fast