@jaimevalasek/aioson 1.3.0

package/template/.aioson/skills/static/nextjs-patterns.md

@@ -0,0 +1,321 @@
+# Next.js Patterns
+
+> App Router, Server Components, and Server Actions. Build fast by default.
+
+---
+
+## Mental model: Server vs Client
+
+```
+Server Components (default) → fetch data, render HTML, never ship JS to browser
+Client Components           → interactivity, useState, useEffect, browser APIs
+Server Actions              → mutations from forms and client events, run on server
+Route Handlers              → REST-like API endpoints (for external consumers)
+```
+
+**Rule:** Start every component as a Server Component. Add `"use client"` only when you need browser APIs, state, or event handlers.
+
+---
+
+## Project structure (App Router)
+
+```
+src/
+  app/
+    (auth)/                  ← route group, no URL segment
+      login/page.tsx
+      register/page.tsx
+      layout.tsx             ← minimal layout for auth pages
+    (dashboard)/
+      layout.tsx             ← authenticated shell (sidebar, nav)
+      page.tsx               ← /dashboard
+      appointments/
+        page.tsx             ← /appointments (list)
+        [id]/
+          page.tsx           ← /appointments/123
+          edit/page.tsx      ← /appointments/123/edit
+      settings/page.tsx
+    api/
+      webhooks/
+        stripe/route.ts      ← POST /api/webhooks/stripe
+  components/
+    ui/                      ← design system primitives (Button, Input, Modal)
+    features/
+      appointments/          ← feature-specific components
+        AppointmentCard.tsx
+        AppointmentList.tsx  ← Server Component (fetches data)
+        BookingForm.tsx      ← Client Component (form state)
+  lib/
+    db.ts                    ← Prisma client singleton
+    auth.ts                  ← NextAuth config
+    stripe.ts                ← Stripe client
+  actions/                   ← Server Actions
+    appointment.actions.ts
+    billing.actions.ts
+  types/
+    index.ts
+```
+
+---
+
+## Data fetching — Server Components
+
+```tsx
+// app/(dashboard)/appointments/page.tsx
+// No useEffect, no useState, no API call — just async/await
+export default async function AppointmentsPage() {
+    const session = await auth();
+    if (!session) redirect('/login');
+
+    const appointments = await db.appointment.findMany({
+        where: { userId: session.user.id },
+        include: { doctor: true },
+        orderBy: { date: 'asc' },
+        take: 50,
+    });
+
+    return (
+        <div>
+            <AppointmentList appointments={appointments} />
+        </div>
+    );
+}
+
+// With suspense for streaming
+export default function Page() {
+    return (
+        <Suspense fallback={<AppointmentListSkeleton />}>
+            <AppointmentList />
+        </Suspense>
+    );
+}
+```
+
+---
+
+## Server Actions — mutations
+
+```ts
+// actions/appointment.actions.ts
+'use server';
+
+import { auth } from '@/lib/auth';
+import { redirect } from 'next/navigation';
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+const createSchema = z.object({
+    doctorId: z.string().uuid(),
+    date: z.string().datetime(),
+    notes: z.string().max(500).optional(),
+});
+
+export async function createAppointment(formData: FormData) {
+    const session = await auth();
+    if (!session) throw new Error('Unauthorized');
+
+    const parsed = createSchema.safeParse({
+        doctorId: formData.get('doctorId'),
+        date: formData.get('date'),
+        notes: formData.get('notes'),
+    });
+
+    if (!parsed.success) {
+        return { error: parsed.error.flatten().fieldErrors };
+    }
+
+    // Check for conflicts
+    const conflict = await db.appointment.findFirst({
+        where: {
+            doctorId: parsed.data.doctorId,
+            date: new Date(parsed.data.date),
+            status: { not: 'cancelled' },
+        },
+    });
+
+    if (conflict) {
+        return { error: { date: ['This time slot is not available.'] } };
+    }
+
+    await db.appointment.create({
+        data: { ...parsed.data, userId: session.user.id },
+    });
+
+    revalidatePath('/appointments');
+    redirect('/appointments');
+}
+```
+
+Usage in a Client Component:
+
+```tsx
+'use client';
+
+import { createAppointment } from '@/actions/appointment.actions';
+import { useActionState } from 'react';
+
+export function BookingForm({ doctors }: { doctors: Doctor[] }) {
+    const [state, action, pending] = useActionState(createAppointment, null);
+
+    return (
+        <form action={action}>
+            <select name="doctorId" required>
+                {doctors.map(d => (
+                    <option key={d.id} value={d.id}>{d.name}</option>
+                ))}
+            </select>
+            {state?.error?.doctorId && <p className="text-red-500">{state.error.doctorId[0]}</p>}
+
+            <input name="date" type="datetime-local" required />
+            {state?.error?.date && <p className="text-red-500">{state.error.date[0]}</p>}
+
+            <button type="submit" disabled={pending}>
+                {pending ? 'Booking...' : 'Book Appointment'}
+            </button>
+        </form>
+    );
+}
+```
+
+---
+
+## Client Components — when and how
+
+```tsx
+'use client';  // Only add when needed
+
+// Good reasons for "use client":
+// - useState, useEffect, useReducer
+// - Event handlers (onClick, onChange)
+// - Browser APIs (localStorage, window, navigator)
+// - Third-party libs that need DOM access
+
+import { useState } from 'react';
+
+export function ConfirmDialog({ onConfirm }: { onConfirm: () => void }) {
+    const [open, setOpen] = useState(false);
+
+    return (
+        <>
+            <button onClick={() => setOpen(true)}>Delete</button>
+            {open && (
+                <dialog open>
+                    <p>Are you sure?</p>
+                    <button onClick={() => { onConfirm(); setOpen(false); }}>Confirm</button>
+                    <button onClick={() => setOpen(false)}>Cancel</button>
+                </dialog>
+            )}
+        </>
+    );
+}
+```
+
+**Pass Server data as props — do not re-fetch in Client Components:**
+
+```tsx
+// WRONG — Client Component fetching its own data
+'use client';
+export function AppointmentList() {
+    const [appointments, setAppointments] = useState([]);
+    useEffect(() => { fetch('/api/appointments').then(...) }, []);
+    // ...
+}
+
+// RIGHT — Server Component passes data as props
+// app/page.tsx (Server)
+const appointments = await db.appointment.findMany(...);
+return <AppointmentList appointments={appointments} />;
+
+// components/AppointmentList.tsx (can be Server too, or Client if interactive)
+```
+
+---
+
+## Route Handlers — for external consumers only
+
+```ts
+// app/api/webhooks/stripe/route.ts
+import Stripe from 'stripe';
+
+export async function POST(request: Request) {
+    const signature = request.headers.get('stripe-signature')!;
+    const body = await request.text();
+
+    let event: Stripe.Event;
+    try {
+        event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+    } catch {
+        return new Response('Invalid signature', { status: 400 });
+    }
+
+    switch (event.type) {
+        case 'invoice.paid':
+            await handleInvoicePaid(event.data.object as Stripe.Invoice);
+            break;
+        case 'customer.subscription.deleted':
+            await handleSubscriptionCancelled(event.data.object as Stripe.Subscription);
+            break;
+    }
+
+    return new Response('OK');
+}
+```
+
+Use Route Handlers for webhooks and external API consumers. Use Server Actions for mutations from your own UI.
+
+---
+
+## Metadata and SEO
+
+```tsx
+// app/appointments/[id]/page.tsx
+import type { Metadata } from 'next';
+
+export async function generateMetadata({ params }: { params: { id: string } }): Promise<Metadata> {
+    const appointment = await db.appointment.findUnique({ where: { id: params.id } });
+
+    return {
+        title: `Appointment with ${appointment?.doctor.name}`,
+        description: `Scheduled for ${appointment?.date.toDateString()}`,
+    };
+}
+```
+
+---
+
+## Loading and error states
+
+```tsx
+// app/appointments/loading.tsx — shown while page.tsx is loading
+export default function Loading() {
+    return <AppointmentListSkeleton />;
+}
+
+// app/appointments/error.tsx — caught by nearest error boundary
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+    return (
+        <div>
+            <p>Something went wrong: {error.message}</p>
+            <button onClick={reset}>Try again</button>
+        </div>
+    );
+}
+```
+
+---
+
+## ALWAYS
+- Server Components by default — add `"use client"` only when needed
+- Server Actions for all mutations from your UI
+- Validate in Server Actions with Zod before touching the database
+- `revalidatePath()` after mutations to refresh stale data
+- `Suspense` boundaries with skeletons for streaming
+- `generateMetadata()` for dynamic page titles
+
+## NEVER
+- `useEffect` to fetch data that could be fetched in a Server Component
+- Route Handlers for mutations from your own frontend (use Server Actions)
+- Client Components that re-fetch data they could receive as props
+- `any` in TypeScript — define types for all Prisma responses and API payloads
+- `process.env.*` in Client Components — use only in Server Components or Actions

package/template/.aioson/skills/static/node-express-patterns.md

@@ -0,0 +1,317 @@
+# Node + Express Patterns
+
+> Production-ready Express APIs. Clean layers, typed contracts, centralized error handling.
+
+---
+
+## Project structure
+
+```
+src/
+  routes/           ← HTTP routing only
+    appointments.routes.ts
+    auth.routes.ts
+    index.ts        ← registers all routers
+  controllers/      ← request parsing, response formatting
+    appointments.controller.ts
+  services/         ← business logic, domain operations
+    appointments.service.ts
+    email.service.ts
+  repositories/     ← data access layer (database queries)
+    appointments.repository.ts
+  middleware/
+    auth.middleware.ts
+    validate.middleware.ts
+    error.middleware.ts
+    rate-limit.middleware.ts
+  schemas/          ← Zod schemas for request validation
+    appointment.schema.ts
+  types/
+    index.ts
+  lib/
+    db.ts           ← database client singleton
+    logger.ts       ← winston/pino logger
+  app.ts            ← Express app setup (no listen)
+  server.ts         ← server startup + graceful shutdown
+```
+
+---
+
+## Layer responsibilities
+
+```ts
+// routes — HTTP wiring only
+// src/routes/appointments.routes.ts
+const router = Router();
+router.get('/',    authenticate, AppointmentController.list);
+router.post('/',   authenticate, validate(createAppointmentSchema), AppointmentController.create);
+router.delete('/:id', authenticate, AppointmentController.cancel);
+export default router;
+
+// controllers — parse request, call service, return response
+// src/controllers/appointments.controller.ts
+export const AppointmentController = {
+    create: async (req: Request, res: Response, next: NextFunction) => {
+        try {
+            const appointment = await AppointmentService.create(req.user!.id, req.body);
+            res.status(201).json({ data: appointment });
+        } catch (err) {
+            next(err);
+        }
+    },
+
+    list: async (req: Request, res: Response, next: NextFunction) => {
+        try {
+            const { page = 1, limit = 20 } = req.query;
+            const result = await AppointmentService.listForUser(req.user!.id, { page: +page, limit: +limit });
+            res.json(result);
+        } catch (err) {
+            next(err);
+        }
+    },
+};
+
+// services — business logic
+// src/services/appointments.service.ts
+export const AppointmentService = {
+    create: async (userId: string, data: CreateAppointmentDto): Promise<Appointment> => {
+        const conflict = await AppointmentRepository.findConflict(data.doctorId, data.date);
+        if (conflict) throw new ConflictError('This time slot is already booked.');
+
+        const appointment = await AppointmentRepository.create({ ...data, userId });
+        await EmailService.sendConfirmation(appointment);
+        return appointment;
+    },
+};
+
+// repositories — data access
+// src/repositories/appointments.repository.ts
+export const AppointmentRepository = {
+    findConflict: async (doctorId: string, date: Date): Promise<Appointment | null> => {
+        return db.appointment.findFirst({
+            where: { doctorId, date, status: { not: 'cancelled' } },
+        });
+    },
+
+    create: async (data: Prisma.AppointmentCreateInput): Promise<Appointment> => {
+        return db.appointment.create({ data, include: { doctor: true } });
+    },
+};
+```
+
+---
+
+## Validation middleware with Zod
+
+```ts
+// src/schemas/appointment.schema.ts
+import { z } from 'zod';
+
+export const createAppointmentSchema = z.object({
+    body: z.object({
+        doctorId: z.string().uuid('Invalid doctor ID'),
+        date: z.string().datetime('Invalid date format'),
+        notes: z.string().max(500).optional(),
+    }),
+});
+
+export type CreateAppointmentDto = z.infer<typeof createAppointmentSchema>['body'];
+
+// src/middleware/validate.middleware.ts
+import { AnyZodObject, ZodError } from 'zod';
+
+export const validate = (schema: AnyZodObject) =>
+    async (req: Request, res: Response, next: NextFunction) => {
+        try {
+            await schema.parseAsync({
+                body:   req.body,
+                query:  req.query,
+                params: req.params,
+            });
+            next();
+        } catch (err) {
+            if (err instanceof ZodError) {
+                return res.status(422).json({
+                    error: 'Validation failed',
+                    details: err.flatten().fieldErrors,
+                });
+            }
+            next(err);
+        }
+    };
+```
+
+---
+
+## Authentication middleware
+
+```ts
+// src/middleware/auth.middleware.ts
+import jwt from 'jsonwebtoken';
+
+export const authenticate = (req: Request, res: Response, next: NextFunction) => {
+    const token = req.headers.authorization?.split(' ')[1];
+    if (!token) return res.status(401).json({ error: 'Authentication required.' });
+
+    try {
+        const payload = jwt.verify(token, process.env.JWT_SECRET!) as JwtPayload;
+        req.user = { id: payload.sub!, role: payload.role };
+        next();
+    } catch {
+        res.status(401).json({ error: 'Invalid or expired token.' });
+    }
+};
+
+export const requireRole = (...roles: string[]) =>
+    (req: Request, res: Response, next: NextFunction) => {
+        if (!roles.includes(req.user!.role)) {
+            return res.status(403).json({ error: 'Insufficient permissions.' });
+        }
+        next();
+    };
+```
+
+---
+
+## Centralized error handling
+
+```ts
+// src/lib/errors.ts — domain error classes
+export class AppError extends Error {
+    constructor(public message: string, public statusCode: number) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+export class NotFoundError extends AppError {
+    constructor(msg = 'Resource not found') { super(msg, 404); }
+}
+export class ConflictError extends AppError {
+    constructor(msg = 'Resource conflict') { super(msg, 409); }
+}
+export class ForbiddenError extends AppError {
+    constructor(msg = 'Forbidden') { super(msg, 403); }
+}
+
+// src/middleware/error.middleware.ts — MUST be last middleware registered
+export const errorHandler = (
+    err: Error,
+    req: Request,
+    res: Response,
+    next: NextFunction
+) => {
+    if (err instanceof AppError) {
+        return res.status(err.statusCode).json({ error: err.message });
+    }
+    // Prisma unique constraint violation
+    if (err.constructor.name === 'PrismaClientKnownRequestError' && (err as any).code === 'P2002') {
+        return res.status(409).json({ error: 'A record with this value already exists.' });
+    }
+
+    logger.error({ err, url: req.url, method: req.method });
+    res.status(500).json({ error: 'Internal server error.' });
+};
+```
+
+---
+
+## Rate limiting
+
+```ts
+import rateLimit from 'express-rate-limit';
+
+// General API rate limit
+export const apiLimiter = rateLimit({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 100,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too many requests. Please try again later.' },
+});
+
+// Strict limit for auth endpoints
+export const authLimiter = rateLimit({
+    windowMs: 15 * 60 * 1000,
+    max: 5,
+    message: { error: 'Too many login attempts. Please try again in 15 minutes.' },
+});
+```
+
+---
+
+## App setup
+
+```ts
+// src/app.ts
+import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import compression from 'compression';
+
+const app = express();
+
+// Security
+app.use(helmet());
+app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') }));
+
+// Parsing
+app.use(express.json({ limit: '10mb' }));
+app.use(compression());
+
+// Rate limiting
+app.use('/api/', apiLimiter);
+app.use('/api/auth/', authLimiter);
+
+// Routes
+app.use('/api/appointments', appointmentRoutes);
+app.use('/api/auth', authRoutes);
+
+// Health check
+app.get('/health', (_, res) => res.json({ status: 'ok', uptime: process.uptime() }));
+
+// Error handler — always last
+app.use(errorHandler);
+
+export { app };
+```
+
+---
+
+## Graceful shutdown
+
+```ts
+// src/server.ts
+const server = app.listen(PORT, () => {
+    logger.info(`Server running on port ${PORT}`);
+});
+
+const shutdown = async (signal: string) => {
+    logger.info(`${signal} received — shutting down gracefully`);
+    server.close(async () => {
+        await db.$disconnect();
+        logger.info('Shutdown complete.');
+        process.exit(0);
+    });
+    setTimeout(() => process.exit(1), 10_000); // force exit after 10s
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT',  () => shutdown('SIGINT'));
+```
+
+---
+
+## ALWAYS
+- Separate routes, controllers, services, repositories
+- Validate at the boundary with Zod before touching services
+- Use typed domain error classes (`AppError`, `NotFoundError`, etc.)
+- Register the error handler middleware last
+- Use `next(err)` in controllers — never `res.status(500)` inline
+- Graceful shutdown on SIGTERM/SIGINT
+
+## NEVER
+- Business logic in routes or controllers
+- Raw `try/catch` without `next(err)` in async controllers
+- `console.log` in production — use a structured logger (pino/winston)
+- `process.env.*` without validation at startup
+- Skip rate limiting on auth endpoints