@dennisrongo/skills 0.1.0

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

@@ -0,0 +1,192 @@
+# Form template (React Hook Form + Zod)
+
+## `src/lib/zod-utils.ts`
+
+```ts
+import { z, type ZodTypeAny, ZodEffects, ZodObject, ZodOptional, ZodNullable, ZodString, ZodNumber, ZodBoolean, ZodArray, ZodDefault } from 'zod';
+
+/** Peel `.refine()` / `.transform()` / `.superRefine()` layers to reach the underlying schema. */
+export function unwrapZodEffects<T extends ZodTypeAny>(schema: T): ZodTypeAny {
+  let current: ZodTypeAny = schema;
+  while (current instanceof ZodEffects) {
+    current = current.innerType();
+  }
+  return current;
+}
+
+/** Walk a Zod object schema and produce a defaults object matching its shape. */
+export function getDefaultValuesFromSchema(schema: ZodTypeAny): Record<string, unknown> {
+  const inner = unwrapZodEffects(schema);
+  if (!(inner instanceof ZodObject)) return {};
+
+  const shape = inner.shape as Record<string, ZodTypeAny>;
+  const out: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(shape)) {
+    out[key] = defaultFor(field);
+  }
+  return out;
+}
+
+function defaultFor(field: ZodTypeAny): unknown {
+  let current: ZodTypeAny = field;
+  while (current instanceof ZodEffects) current = current.innerType();
+
+  if (current instanceof ZodDefault) return current._def.defaultValue();
+  if (current instanceof ZodOptional) return undefined;
+  if (current instanceof ZodNullable) return null;
+  if (current instanceof ZodString) return '';
+  if (current instanceof ZodNumber) return undefined; // empty number input
+  if (current instanceof ZodBoolean) return false;
+  if (current instanceof ZodArray) return [];
+  if (current instanceof ZodObject) return getDefaultValuesFromSchema(current);
+  return undefined;
+}
+
+/** Extract `.max(N)` constraints from string fields for `maxLength` attributes. */
+export function getMaxLengthsFromSchema(schema: ZodTypeAny): Record<string, number> {
+  const inner = unwrapZodEffects(schema);
+  if (!(inner instanceof ZodObject)) return {};
+
+  const out: Record<string, number> = {};
+  for (const [key, field] of Object.entries(inner.shape as Record<string, ZodTypeAny>)) {
+    let current: ZodTypeAny = field;
+    while (current instanceof ZodEffects || current instanceof ZodOptional || current instanceof ZodNullable || current instanceof ZodDefault) {
+      current = current instanceof ZodDefault ? current._def.innerType : (current as ZodOptional<ZodTypeAny>).unwrap?.() ?? (current as ZodEffects<ZodTypeAny>).innerType?.();
+    }
+    if (current instanceof ZodString) {
+      const max = current._def.checks?.find((c) => c.kind === 'max');
+      if (max && 'value' in max) out[key] = max.value as number;
+    }
+  }
+  return out;
+}
+```
+
+> The exact `_def` access details depend on the Zod major version. Verify against the version chosen at scaffold time (resolve via context7) and adapt — Zod's runtime introspection API has shifted between v3 and later versions.
+
+## Composed form field — `src/components/forms/FormInputField.tsx`
+
+```tsx
+'use client';
+
+import type { ComponentProps } from 'react';
+import type { FieldValues, Path, UseFormReturn } from 'react-hook-form';
+import type { ZodTypeAny } from 'zod';
+import { FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { Input } from '@/components/ui/input';
+import { getMaxLengthsFromSchema } from '@/lib/zod-utils';
+
+interface FormInputFieldProps<TForm extends FieldValues> {
+  form: UseFormReturn<TForm>;
+  schema?: ZodTypeAny;
+  fieldName: Path<TForm>;
+  label: string;
+  placeholder?: string;
+  type?: ComponentProps<typeof Input>['type'];
+}
+
+export function FormInputField<TForm extends FieldValues>({
+  form,
+  schema,
+  fieldName,
+  label,
+  placeholder,
+  type = 'text',
+}: FormInputFieldProps<TForm>) {
+  const maxLengths = schema ? getMaxLengthsFromSchema(schema) : {};
+  return (
+    <FormField
+      control={form.control}
+      name={fieldName}
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>{label}</FormLabel>
+          <FormControl>
+            <Input
+              type={type}
+              placeholder={placeholder}
+              maxLength={maxLengths[String(fieldName)]}
+              {...field}
+              value={field.value ?? ''}
+            />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
+```
+
+**No `dangerouslySetInnerHTML` for the label.** Labels are strings. If a future requirement is "render an inline `<strong>` in the label," accept a `ReactNode` instead of a string — never raw HTML.
+
+## A real form — `src/app/(public)/auth/login/_components/LoginForm.tsx`
+
+```tsx
+'use client';
+
+import { useRouter, useSearchParams } from 'next/navigation';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+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 { getDefaultValuesFromSchema, unwrapZodEffects } from '@/lib/zod-utils';
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8).max(128),
+});
+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 form = useForm<LoginValues>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: getDefaultValuesFromSchema(unwrapZodEffects(loginSchema)) as LoginValues,
+  });
+
+  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' });
+    }
+  };
+
+  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'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## `UnsavedChangesWarning` integration
+
+For non-trivial forms, wrap the submit area with the guard:
+
+```tsx
+import { UnsavedChangesWarning } from '@/components/UnsavedChangesWarning';
+
+// inside the form:
+<UnsavedChangesWarning when={form.formState.isDirty && !form.formState.isSubmitting} />
+```
+
+`UnsavedChangesWarning` uses `window.beforeunload` + a Next router-events listener to prompt before navigating away.

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

@@ -0,0 +1,88 @@
+# `middleware.ts` template
+
+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
+
+```ts
+// middleware.ts
+import { NextResponse, type NextRequest } from 'next/server';
+
+const PROTECTED_PREFIXES = ['/app', '/admin'];
+const AUTH_PATH = '/auth/login';
+
+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}/`));
+
+  // 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);
+  }
+
+  // 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);
+  }
+
+  return NextResponse.next();
+}
+
+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)
+
+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:
+
+```ts
+import { NextResponse, type NextRequest } from 'next/server';
+import { jwtVerify } from 'jose'; // Edge-compatible; do not use jwt-decode here.
+
+const PROTECTED_PREFIXES = ['/app', '/admin'];
+const SECRET = new TextEncoder().encode(process.env.JWT_VERIFY_KEY!);
+
+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}/`));
+
+  if (!isProtected) return NextResponse.next();
+  if (!token) return redirectToLogin(req);
+
+  try {
+    await jwtVerify(token, SECRET);
+    return NextResponse.next();
+  } catch {
+    return redirectToLogin(req);
+  }
+}
+
+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);
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+**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.

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

@@ -0,0 +1,42 @@
+# `next.config.ts` template
+
+```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*`,
+      },
+    ];
+  },
+
+  images: {
+    remotePatterns: [
+      // Add allowed external image hosts here. Leave empty by default.
+    ],
+  },
+
+  experimental: {
+    // Enable on a case-by-case basis only.
+  },
+};
+
+export default nextConfig;
+```
+
+**Notes:**
+- 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.
+- `reactStrictMode: true` is non-negotiable for a new project.
+- `poweredByHeader: false` removes the `X-Powered-By` header.

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

@@ -0,0 +1,99 @@
+# `package.json` template
+
+Resolve **every** version via context7 at scaffold time. Versions below are placeholders (`"^x.y.z"`) — replace with the latest stable resolved at scaffold time and quote the resolved versions back to the user.
+
+```jsonc
+{
+  "name": "{{project-name}}",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "{{pnpm|npm|yarn}}@x.y.z",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "next": "^x.y.z",
+    "react": "^x.y.z",
+    "react-dom": "^x.y.z",
+
+    "@reduxjs/toolkit": "^x.y.z",
+    "react-redux": "^x.y.z",
+
+    "react-hook-form": "^x.y.z",
+    "@hookform/resolvers": "^x.y.z",
+    "zod": "^x.y.z",
+
+    "@radix-ui/react-dialog": "^x.y.z",
+    "@radix-ui/react-dropdown-menu": "^x.y.z",
+    "@radix-ui/react-label": "^x.y.z",
+    "@radix-ui/react-popover": "^x.y.z",
+    "@radix-ui/react-select": "^x.y.z",
+    "@radix-ui/react-slot": "^x.y.z",
+    "@radix-ui/react-toast": "^x.y.z",
+    "class-variance-authority": "^x.y.z",
+    "clsx": "^x.y.z",
+    "tailwind-merge": "^x.y.z",
+    "tailwindcss-animate": "^x.y.z",
+    "lucide-react": "^x.y.z",
+
+    "date-fns": "^x.y.z",
+    "next-nprogress-bar": "^x.y.z"
+  },
+  "devDependencies": {
+    "typescript": "^x.y.z",
+    "@types/node": "^x.y.z",
+    "@types/react": "^x.y.z",
+    "@types/react-dom": "^x.y.z",
+
+    "tailwindcss": "^x.y.z",
+    "postcss": "^x.y.z",
+    "autoprefixer": "^x.y.z",
+
+    "eslint": "^x.y.z",
+    "eslint-config-next": "^x.y.z",
+    "@typescript-eslint/eslint-plugin": "^x.y.z",
+    "@typescript-eslint/parser": "^x.y.z",
+    "eslint-plugin-react-hooks": "^x.y.z",
+    "eslint-plugin-jsx-a11y": "^x.y.z",
+    "prettier": "^x.y.z",
+    "prettier-plugin-tailwindcss": "^x.y.z",
+
+    "husky": "^x.y.z",
+    "lint-staged": "^x.y.z",
+
+    "vitest": "^x.y.z",
+    "@vitejs/plugin-react": "^x.y.z",
+    "@testing-library/react": "^x.y.z",
+    "@testing-library/jest-dom": "^x.y.z",
+    "@testing-library/user-event": "^x.y.z",
+    "jsdom": "^x.y.z",
+    "@playwright/test": "^x.y.z"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": ["prettier --write", "eslint --fix"],
+    "*.{json,md,css,yml,yaml}": ["prettier --write"]
+  }
+}
+```
+
+**Do NOT include:**
+- `moment` (use `date-fns`)
+- `styled-components` / `@emotion/*` (project is Tailwind-only)
+- `nprogress` (use `next-nprogress-bar`)
+- A `proxy` library at the application layer (use Next.js `rewrites()` in `next.config.ts`)
+
+**Add only if the user opted in during Step 2:**
+- `pusher-js` (real-time)
+- Storybook packages
+- `next-intl` / `next-i18next` (i18n)
+- `@sentry/nextjs` (error tracking)

package/skills/nextjs-app-router/references/templates/providers-and-store.md

@@ -0,0 +1,79 @@
+# Providers, store, typed hooks
+
+## `src/redux/providers.tsx` (CLIENT — this one must be client because of `<Provider store>`)
+
+```tsx
+'use client';
+
+import { Provider } from 'react-redux';
+import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';
+import { Toaster } from '@/components/ui/toaster';
+import { store } from './store';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <Provider store={store}>
+      {children}
+      <Toaster />
+      <ProgressBar
+        height="3px"
+        color="hsl(var(--primary))"
+        shallowRouting
+        disableSameURL
+        options={{ showSpinner: false }}
+      />
+    </Provider>
+  );
+}
+```
+
+## `src/redux/store.ts`
+
+```ts
+import { combineReducers, configureStore, type Action } from '@reduxjs/toolkit';
+import { api } from './api/api';
+import { authApi } from './api/authApi';
+import { authSlice } from './features/authSlice';
+
+const combinedReducer = combineReducers({
+  [api.reducerPath]: api.reducer,
+  auth: authSlice.reducer,
+});
+
+type CombinedState = ReturnType<typeof combinedReducer>;
+
+const rootReducer = (state: CombinedState | undefined, action: Action): CombinedState => {
+  // Wipe the entire store on logout. RTK Query cache, auth, everything.
+  if (authApi.endpoints.logout.matchFulfilled(action)) {
+    return combinedReducer(undefined, action);
+  }
+  return combinedReducer(state, action);
+};
+
+export const store = configureStore({
+  reducer: rootReducer,
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware({
+      // Keep serializableCheck ON. If a specific value is genuinely non-serializable,
+      // add it here with a comment explaining why.
+      // serializableCheck: { ignoredPaths: ['auth.expiresAt'] },
+    }).concat(api.middleware),
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+```
+
+**No `@ts-ignore`. No `serializableCheck: false`. No commented-out reducers.**
+
+## `src/redux/hooks.ts`
+
+```ts
+import { useDispatch, useSelector, type TypedUseSelectorHook } from 'react-redux';
+import type { AppDispatch, RootState } from './store';
+
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+```
+
+Components import `useAppDispatch` / `useAppSelector` — never the raw `useDispatch` / `useSelector` from `react-redux`. ESLint can enforce this with `no-restricted-imports` if desired.

package/skills/nextjs-app-router/references/templates/root-layout.md

@@ -0,0 +1,146 @@
+# Root layout, root page, error/not-found templates
+
+## `src/app/layout.tsx` (SERVER component)
+
+```tsx
+import '@/app/globals.css';
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import { Providers } from '@/redux/providers';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata: Metadata = {
+  title: '{{Project Title}}',
+  description: '{{Project description}}',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={inter.className}>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+**NO `'use client'`. NO `useEffect`. NO `useRouter`.** The root layout is a server component.
+
+## `src/app/page.tsx` (SERVER component, redirect-only)
+
+If the project has an authenticated landing route, the root page is a server `redirect`:
+
+```tsx
+import { redirect } from 'next/navigation';
+
+export default function Home() {
+  redirect('/dashboard');
+}
+```
+
+If the project has a marketing landing page, render content instead — still as a server component, no `'use client'`.
+
+**Forbidden:**
+
+```tsx
+// ❌ DO NOT generate this.
+'use client';
+import { useRouter } from 'next/navigation';
+import { useEffect } from 'react';
+export default function Home() {
+  const router = useRouter();
+  useEffect(() => router.push('/dashboard'));
+}
+```
+
+## `src/app/error.tsx` (CLIENT — Next requires it)
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { Button } from '@/components/ui/button';
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    // Wire to your error tracker (Sentry, etc.) if configured.
+    console.error(error);
+  }, [error]);
+
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-4">
+      <h1 className="text-2xl font-semibold">Something went wrong</h1>
+      <p className="text-muted-foreground">{error.message}</p>
+      <Button onClick={reset}>Try again</Button>
+    </div>
+  );
+}
+```
+
+## `src/app/not-found.tsx` (SERVER component)
+
+```tsx
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
+
+export default function NotFound() {
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-4">
+      <h1 className="text-3xl font-semibold">404 — Page not found</h1>
+      <Button asChild>
+        <Link href="/">Go home</Link>
+      </Button>
+    </div>
+  );
+}
+```
+
+## `src/app/globals.css` (Tailwind layer + shadcn CSS variables)
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 3.9%;
+    --primary: 240 5.9% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 46.1%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240 5.9% 10%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    /* ... dark counterparts ... */
+  }
+
+  * { @apply border-border; }
+  body { @apply bg-background text-foreground; }
+}
+```