@dennisrongo/skills 0.1.2 → 0.2.0

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

@@ -1,71 +1,66 @@
 # Feature slice template (Mode 2 — `add-feature`)
 
-A feature is a route folder under a route group, with its own private `_components/` and `_hooks/`, a local Zod `schema.ts`, and (usually) one or more RTK Query endpoints injected into the appropriate domain slice.
+A feature is a route folder under a route group, with its own private `_components/` and `_hooks/`, a local Zod `schema.ts` (shared with the matching Route Handler), and one or more RTK Query endpoints injected into the appropriate domain slice. **Every `page.tsx` is `'use client'`**.
 
-## Layout for feature `{{feature}}` under `(app)`
+## Layout for feature `{{feature}}` under `(app)` (list + create + edit)
 
 ```
-src/app/(app)/{{feature}}/
-├── page.tsx                   # SERVER component (renders client child if interactive)
-├── loading.tsx
-├── error.tsx                  # optional but recommended
-├── schema.ts                  # Zod schemas owned by this feature
-├── _components/
-│   ├── {{Feature}}Table.tsx   # 'use client' if it has interactions
-│   └── {{Feature}}Form.tsx    # 'use client'
-└── _hooks/
-    └── use{{Feature}}Filters.ts
-```
-
-For a feature with sub-routes (list + detail + new):
-
-```
-src/app/(app)/{{feature}}/
-├── page.tsx                   # list
-├── new/
-│   └── page.tsx               # SERVER renders <{{Feature}}Form mode="create" />
+src/app/(app)/{{feature}}s/
+├── page.tsx                   # 'use client' — list view, uses useGet{{Feature}}sQuery
+├── new/page.tsx               # 'use client' — renders <{{Feature}}Form mode="create" />
 ├── [id]/
-│   ├── page.tsx               # SERVER renders <{{Feature}}Form mode="edit" id={id} />
+│   ├── page.tsx               # 'use client' — renders <{{Feature}}Form mode="edit" id={params.id} />
 │   ├── loading.tsx
-│   └── _components/{{Feature}}DetailPanel.tsx
-├── schema.ts
+│   └── _components/
+├── loading.tsx
+├── error.tsx
+├── schema.ts                  # Zod — SHARED with src/app/api/{{feature}}/route.ts
 ├── _components/
-│   ├── {{Feature}}Table.tsx
+│   ├── {{Feature}}sTable.tsx
 │   └── {{Feature}}Form.tsx
 └── _hooks/
+    └── use{{Feature}}Filters.ts
+
+src/app/api/{{feature}}s/
+├── route.ts                   # GET (list) + POST (create)
+└── [id]/route.ts              # GET + PATCH + DELETE
 ```
 
-## `page.tsx` for the list view (SERVER)
+## `page.tsx` for the list view (CLIENT)
 
 ```tsx
-import { Suspense } from 'react';
-import { {{Feature}}Table } from './_components/{{Feature}}Table';
+'use client';
 
-export const metadata = { title: '{{Feature}}s' };
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
+import { {{Feature}}sTable } from './_components/{{Feature}}sTable';
 
 export default function {{Feature}}sPage() {
   return (
     <section className="space-y-4">
       <header className="flex items-center justify-between">
         <h1 className="text-2xl font-semibold">{{Feature}}s</h1>
+        <Button asChild>
+          <Link href="/app/{{feature}}s/new">New {{feature}}</Link>
+        </Button>
       </header>
-      <Suspense fallback={<div>Loading…</div>}>
-        <{{Feature}}Table />
-      </Suspense>
+      <{{Feature}}sTable />
     </section>
   );
 }
 ```
 
-## `_components/{{Feature}}Table.tsx` (CLIENT)
+Per-route metadata for client pages lives at the layout level (server). If this feature needs a specific `<title>`, lift it into a `(app)/{{feature}}s/layout.tsx` server component with a `metadata` export.
+
+## `_components/{{Feature}}sTable.tsx` (CLIENT)
 
 ```tsx
 'use client';
 
-import { use{{Feature}}sQuery } from '@/redux/api/{{feature}}sApi';
+import { useGet{{Feature}}sQuery } from '@/redux/api/{{feature}}sApi';
 
 export function {{Feature}}sTable() {
-  const { data, isLoading, error } = use{{Feature}}sQuery();
+  const { data, isLoading, error } = useGet{{Feature}}sQuery();
 
   if (isLoading) return <p className="text-muted-foreground">Loading…</p>;
   if (error) return <p className="text-destructive">Failed to load.</p>;
@@ -92,7 +87,7 @@ export function {{Feature}}sTable() {
 }
 ```
 
-## `schema.ts`
+## `schema.ts` (SHARED with Route Handler)
 
 ```ts
 import { z } from 'zod';
@@ -105,6 +100,44 @@ export const {{feature}}Schema = z.object({
 export type {{Feature}}FormValues = z.infer<typeof {{feature}}Schema>;
 ```
 
+The matching `src/app/api/{{feature}}s/route.ts` imports `{{feature}}Schema` and calls `{{feature}}Schema.safeParse(await req.json())`. One schema, two sides.
+
+## `new/page.tsx` (CLIENT)
+
+```tsx
+'use client';
+
+import { {{Feature}}Form } from '../_components/{{Feature}}Form';
+
+export default function New{{Feature}}Page() {
+  return (
+    <section className="space-y-4">
+      <h1 className="text-2xl font-semibold">New {{feature}}</h1>
+      <{{Feature}}Form mode="create" />
+    </section>
+  );
+}
+```
+
+## `[id]/page.tsx` (CLIENT)
+
+```tsx
+'use client';
+
+import { useParams } from 'next/navigation';
+import { {{Feature}}Form } from '../_components/{{Feature}}Form';
+
+export default function Edit{{Feature}}Page() {
+  const params = useParams<{ id: string }>();
+  return (
+    <section className="space-y-4">
+      <h1 className="text-2xl font-semibold">Edit {{feature}}</h1>
+      <{{Feature}}Form mode="edit" id={params.id} />
+    </section>
+  );
+}
+```
+
 ## `_components/{{Feature}}Form.tsx` (CLIENT)
 
 ```tsx
@@ -118,25 +151,47 @@ import { Button } from '@/components/ui/button';
 import { FormInputField } from '@/components/forms/FormInputField';
 import { UnsavedChangesWarning } from '@/components/UnsavedChangesWarning';
 import { useToast } from '@/components/ui/use-toast';
-import { useCreate{{Feature}}Mutation } from '@/redux/api/{{feature}}sApi';
+import {
+  useCreate{{Feature}}Mutation,
+  useUpdate{{Feature}}Mutation,
+  useGet{{Feature}}Query,
+} from '@/redux/api/{{feature}}sApi';
 import { getDefaultValuesFromSchema, unwrapZodEffects } from '@/lib/zod-utils';
 import { {{feature}}Schema, type {{Feature}}FormValues } from '../schema';
 
-export function {{Feature}}Form() {
+interface Props {
+  mode: 'create' | 'edit';
+  id?: string;
+}
+
+export function {{Feature}}Form({ mode, id }: Props) {
   const router = useRouter();
   const { toast } = useToast();
-  const [create, { isLoading }] = useCreate{{Feature}}Mutation();
+
+  const { data: existing } = useGet{{Feature}}Query(id ?? '', { skip: mode !== 'edit' || !id });
+  const [create, { isLoading: isCreating }] = useCreate{{Feature}}Mutation();
+  const [update, { isLoading: isUpdating }] = useUpdate{{Feature}}Mutation();
 
   const form = useForm<{{Feature}}FormValues>({
     resolver: zodResolver({{feature}}Schema),
-    defaultValues: getDefaultValuesFromSchema(unwrapZodEffects({{feature}}Schema)) as {{Feature}}FormValues,
+    defaultValues:
+      existing ??
+      (getDefaultValuesFromSchema(unwrapZodEffects({{feature}}Schema)) as {{Feature}}FormValues),
+    values: existing,
   });
 
+  const isSubmitting = isCreating || isUpdating;
+
   const onSubmit = async (values: {{Feature}}FormValues) => {
     try {
-      const created = await create(values).unwrap();
-      toast({ title: '{{Feature}} created.' });
-      router.replace(`/app/{{feature}}s/${created.id}`);
+      if (mode === 'create') {
+        const created = await create(values).unwrap();
+        toast({ title: '{{Feature}} created.' });
+        router.replace(`/app/{{feature}}s/${created.id}`);
+      } else if (id) {
+        await update({ id, patch: values }).unwrap();
+        toast({ title: '{{Feature}} updated.' });
+      }
     } catch {
       toast({ title: 'Could not save', variant: 'destructive' });
     }
@@ -149,8 +204,12 @@ export function {{Feature}}Form() {
         <FormInputField form={form} schema={{feature}}Schema} fieldName="name" label="Name" />
         <FormInputField form={form} schema={{feature}}Schema} fieldName="email" label="Email" type="email" />
         <div className="flex gap-2">
-          <Button type="submit" disabled={isLoading}>{isLoading ? 'Saving…' : 'Save'}</Button>
-          <Button type="button" variant="ghost" onClick={() => router.back()}>Cancel</Button>
+          <Button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? 'Saving…' : 'Save'}
+          </Button>
+          <Button type="button" variant="ghost" onClick={() => router.back()}>
+            Cancel
+          </Button>
         </div>
       </form>
     </Form>
@@ -179,6 +238,10 @@ describe('{{feature}}Schema', () => {
 });
 ```
 
-## Endpoint additions
+## Route Handlers
+
+Always generate the matching `src/app/api/{{feature}}s/route.ts` and `[id]/route.ts` alongside the client-side feature. See [`route-handler.md`](route-handler.md).
+
+## Endpoint additions to the RTK slice
 
-If the domain slice doesn't exist yet, run Mode 3 first (`add-api-slice`). Then add the feature's query/mutation pair to that slice — see [`api-slice.md`](api-slice.md).
+If the domain slice doesn't exist yet, run Mode 3 (`add-api-slice`). Then add the feature's query/mutation pair — see [`api-slice.md`](api-slice.md).

package/skills/nextjs-app-router/references/templates/form-with-zod.md

@@ -122,10 +122,14 @@ export function FormInputField<TForm extends FieldValues>({
 
 ## A real form — `src/app/(public)/auth/login/_components/LoginForm.tsx`
 
+The login form uses NextAuth's `signIn` directly — there is no `useLoginMutation` because auth is not a domain in the RTK Query slice.
+
 ```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';
@@ -133,22 +137,20 @@ import { z } from 'zod';
 import { Form } from '@/components/ui/form';
 import { Button } from '@/components/ui/button';
 import { FormInputField } from '@/components/forms/FormInputField';
-import { useLoginMutation } from '@/redux/api/authApi';
-import { useToast } from '@/components/ui/use-toast';
+import { FormPasswordField } from '@/components/forms/FormPasswordField';
 import { getDefaultValuesFromSchema, unwrapZodEffects } from '@/lib/zod-utils';
 
 const loginSchema = z.object({
   email: z.string().email(),
-  password: z.string().min(8).max(128),
+  password: z.string().min(1, 'Required'),
 });
 type LoginValues = z.infer<typeof loginSchema>;
 
 export function LoginForm() {
   const router = useRouter();
   const searchParams = useSearchParams();
-  const returnTo = searchParams.get('returnTo') ?? '/dashboard';
-  const { toast } = useToast();
-  const [login, { isLoading }] = useLoginMutation();
+  const returnTo = searchParams.get('returnTo') ?? '/app/dashboard';
+  const [error, setError] = useState<string | null>(null);
 
   const form = useForm<LoginValues>({
     resolver: zodResolver(loginSchema),
@@ -156,21 +158,25 @@ export function LoginForm() {
   });
 
   const onSubmit = async (values: LoginValues) => {
-    try {
-      await login(values).unwrap();
-      router.replace(returnTo);
-    } catch (err) {
-      toast({ title: 'Sign in failed', description: String((err as { data?: { message?: string } }).data?.message ?? 'Try again.'), variant: 'destructive' });
+    setError(null);
+    const res = await signIn('credentials', { ...values, redirect: false });
+    if (res?.error) {
+      // Don't reveal which field was wrong — security best practice.
+      setError('Invalid email or password.');
+      return;
     }
+    router.replace(returnTo);
+    router.refresh();
   };
 
   return (
     <Form {...form}>
       <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-        <FormInputField form={form} schema={loginSchema} fieldName="email" label="Email" type="email" />
-        <FormInputField form={form} schema={loginSchema} fieldName="password" label="Password" type="password" />
-        <Button type="submit" disabled={isLoading} className="w-full">
-          {isLoading ? 'Signing in…' : 'Sign in'}
+        {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" disabled={form.formState.isSubmitting} className="w-full">
+          {form.formState.isSubmitting ? 'Signing in…' : 'Sign in'}
         </Button>
       </form>
     </Form>
@@ -178,6 +184,8 @@ export function LoginForm() {
 }
 ```
 
+**Why no `useLoginMutation`:** auth flows go through NextAuth (`signIn` / `signOut`), not through RTK Query. RTK Query is for domain data. Keeping these separate avoids the temptation to re-implement session state inside Redux.
+
 ## `UnsavedChangesWarning` integration
 
 For non-trivial forms, wrap the submit area with the guard:

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

@@ -1,88 +1,98 @@
-# `middleware.ts` template
+# `middleware.ts` template (NextAuth-driven)
 
 This is **the** auth gate. Place at the project root (not in `src/`). Next.js requires this exact filename and location.
 
-## Variant A — `httpOnly` cookie set by the backend on login
+## Variant A — Plain NextAuth `auth` (covers most projects)
 
 ```ts
 // middleware.ts
-import { NextResponse, type NextRequest } from 'next/server';
+import NextAuth from 'next-auth';
+import authConfig from '@/auth.config';
 
-const PROTECTED_PREFIXES = ['/app', '/admin'];
-const AUTH_PATH = '/auth/login';
+export const { auth: middleware } = NextAuth(authConfig);
 
-export function middleware(req: NextRequest) {
-  const { pathname, search } = req.nextUrl;
-  const session = req.cookies.get('session')?.value;
-  const isProtected = PROTECTED_PREFIXES.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+// Exclude NextAuth's own API routes and static assets.
+export const config = {
+  matcher: ['/((?!api/auth|_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)'],
+};
+```
 
-  // Already authenticated user hitting an auth page → bounce to /app.
-  if (session && pathname.startsWith('/auth')) {
-    const url = req.nextUrl.clone();
-    url.pathname = '/app/dashboard';
-    url.search = '';
-    return NextResponse.redirect(url);
-  }
+NextAuth's `auth` returns 302s to `pages.signIn` for unauthenticated requests to anything matched by the `authorized` callback in `auth.config.ts`. If `authorized` isn't defined, all matched routes require a session.
 
-  // Unauthenticated user hitting a protected route → redirect with returnTo.
-  if (!session && isProtected) {
-    const url = req.nextUrl.clone();
-    url.pathname = AUTH_PATH;
-    url.search = '';
-    url.searchParams.set('returnTo', pathname + search);
-    return NextResponse.redirect(url);
-  }
+The `authorized` callback in `auth.config.ts`:
 
-  return NextResponse.next();
+```ts
+// inside src/auth.config.ts
+callbacks: {
+  authorized({ auth, request: { nextUrl } }) {
+    const isLoggedIn = !!auth?.user;
+    const isOnPublic = nextUrl.pathname.startsWith('/auth');
+    if (isOnPublic) {
+      return isLoggedIn
+        ? Response.redirect(new URL('/app/dashboard', nextUrl))
+        : true;
+    }
+    return isLoggedIn; // false → redirected to pages.signIn
+  },
 }
-
-export const config = {
-  // Run on everything except Next internals and static assets.
-  matcher: ['/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)'],
-};
 ```
 
-## Variant B — JS-readable cookie (decode the JWT here)
+## Variant B — Custom wrapper for role/path logic
 
-If the backend cannot set an `httpOnly` cookie and the project must use a JS-readable token, decode the JWT in middleware to check expiry — never trust the client to have done so:
+When `(admin)` exists or `/` needs role-based routing:
 
 ```ts
-import { NextResponse, type NextRequest } from 'next/server';
-import { jwtVerify } from 'jose'; // Edge-compatible; do not use jwt-decode here.
+// middleware.ts
+import NextAuth from 'next-auth';
+import { NextResponse } from 'next/server';
+import authConfig from '@/auth.config';
 
-const PROTECTED_PREFIXES = ['/app', '/admin'];
-const SECRET = new TextEncoder().encode(process.env.JWT_VERIFY_KEY!);
+const { auth } = NextAuth(authConfig);
 
-export async function middleware(req: NextRequest) {
-  const token = req.cookies.get('token')?.value;
-  const { pathname, search } = req.nextUrl;
-  const isProtected = PROTECTED_PREFIXES.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+export default auth((req) => {
+  const { pathname } = req.nextUrl;
+  const session = req.auth;
 
-  if (!isProtected) return NextResponse.next();
-  if (!token) return redirectToLogin(req);
+  // Root redirect
+  if (pathname === '/') {
+    const url = req.nextUrl.clone();
+    url.pathname = session ? '/app/dashboard' : '/auth/login';
+    return NextResponse.redirect(url);
+  }
 
-  try {
-    await jwtVerify(token, SECRET);
-    return NextResponse.next();
-  } catch {
-    return redirectToLogin(req);
+  // Admin gate
+  if (pathname.startsWith('/admin')) {
+    if (!session) {
+      const url = req.nextUrl.clone();
+      url.pathname = '/auth/login';
+      url.searchParams.set('returnTo', pathname);
+      return NextResponse.redirect(url);
+    }
+    if (session.user?.role !== 'admin') {
+      return new NextResponse('Forbidden', { status: 403 });
+    }
   }
-}
 
-function redirectToLogin(req: NextRequest) {
-  const url = req.nextUrl.clone();
-  url.pathname = '/auth/login';
-  url.searchParams.set('returnTo', req.nextUrl.pathname + req.nextUrl.search);
-  return NextResponse.redirect(url);
-}
+  // App gate
+  if (pathname.startsWith('/app') && !session) {
+    const url = req.nextUrl.clone();
+    url.pathname = '/auth/login';
+    url.searchParams.set('returnTo', pathname);
+    return NextResponse.redirect(url);
+  }
+
+  return NextResponse.next();
+});
 
 export const config = {
-  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+  matcher: ['/((?!api/auth|_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)'],
 };
 ```
 
 **Notes:**
-- `jose` is Edge-runtime compatible. `jsonwebtoken` and `jwt-decode` are not — they assume Node.
-- The matcher must exclude `_next/static`, `_next/image`, and `favicon.ico`. Add other public assets as needed.
-- Do **not** add a `src/proxy.ts` or `src/middleware.ts` — Next.js only looks at `middleware.ts` at the project root.
-- Role-gating for `/admin` happens here too: decode the role claim and 403 (or redirect) when the user is not allowed.
+
+- `auth.config.ts` must be **Edge-safe**: no Prisma adapter, no `@/lib/db`, no Node-only imports. The middleware runs on the Edge runtime; importing Node-only code crashes the production build with a confusing "module not found in edge runtime" error.
+- The matcher excludes `api/auth` so NextAuth's own `/api/auth/[...nextauth]` route is reachable without recursion.
+- Other `/api/**` routes (your Route Handlers) are excluded *from middleware redirects* because the matcher targets pages — handlers run their own `requireSession()` check and return JSON 401s rather than 302s.
+- Role claims: add them in the `jwt` callback inside `auth.config.ts` (or `auth.ts` if the role comes from the DB). Module-augment `Session` and `JWT` in `src/types/next-auth.d.ts`.
+- Do **not** add a `src/proxy.ts` or `src/middleware/*.ts` — Next.js only looks at `middleware.ts` at the project root.

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

@@ -3,23 +3,12 @@
 ```ts
 import type { NextConfig } from 'next';
 
-const apiBase = process.env.NEXT_PUBLIC_API_BASE_URL;
-
 const nextConfig: NextConfig = {
   reactStrictMode: true,
   poweredByHeader: false,
 
-  // Forward /api/* to the backend in production; in dev, hit the backend directly via NEXT_PUBLIC_API_BASE_URL.
-  // Configure only if the user opted into the rewrite pattern in Step 2.
-  async rewrites() {
-    if (!apiBase) return [];
-    return [
-      {
-        source: '/api/:path*',
-        destination: `${apiBase}/:path*`,
-      },
-    ];
-  },
+  // The backend is in-app under src/app/api/**/route.ts. No rewrites are needed.
+  // (Do not add a rewrite forwarding /api/* to an external host — this project is fullstack.)
 
   images: {
     remotePatterns: [
@@ -36,7 +25,8 @@ export default nextConfig;
 ```
 
 **Notes:**
+- The app is fullstack: `/api/*` routes are Route Handlers in `src/app/api/**/route.ts`, not proxies to an external backend. **Do not** add a `rewrites()` entry forwarding `/api/*` to another host — that breaks NextAuth (which expects `/api/auth/*` to land on the in-app handlers) and removes the same-origin guarantee RTK Query relies on for `credentials: 'include'`.
 - Do not enable `output: 'standalone'` by default; only when the user is deploying to a container.
-- Do not enable `output: 'export'` (static export) unless the user explicitly asks — it disables middleware, server components data fetching, and image optimization.
+- Do not enable `output: 'export'` (static export) — it disables middleware, Route Handlers, and image optimization. The skill's whole architecture depends on those.
 - `reactStrictMode: true` is non-negotiable for a new project.
 - `poweredByHeader: false` removes the `X-Powered-By` header.