@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/add-role/SKILL.md

@@ -0,0 +1,156 @@
+# Skill: Add a User Role
+
+Add a new role to the MARS role-based access control system.
+
+## When to Use
+
+Use this skill when the user asks to add a new role (e.g., "moderator", "editor", "manager"), restrict access by role, or implement role-based permissions.
+
+## Architecture
+
+MARS uses string-based roles (not enums) stored on the User model. This is intentional -- string roles are more flexible for migrations than Prisma enums.
+
+## Step 1: Define the Role
+
+Add the role to your application's type system. Create or update `src/features/admin/types.ts`:
+
+```typescript
+export const ROLES = ['user', 'admin', 'moderator', 'editor'] as const;
+export type Role = (typeof ROLES)[number];
+
+export const ROLE_HIERARCHY: Record<Role, number> = {
+  user: 0,
+  editor: 1,
+  moderator: 2,
+  admin: 3,
+};
+
+export function hasMinimumRole(userRole: string, requiredRole: Role): boolean {
+  return (ROLE_HIERARCHY[userRole as Role] ?? 0) >= ROLE_HIERARCHY[requiredRole];
+}
+```
+
+## Step 2: Protect API Routes
+
+Use `withRole` for routes that require specific roles:
+
+```typescript
+import { withRole } from '@/lib/mars';
+
+// Only admins and moderators
+export const DELETE = withRole(['admin', 'moderator'], async (request, context) => {
+  // ...
+});
+
+// Only admins
+export const PATCH = withRole(['admin'], async (request, context) => {
+  // ...
+});
+```
+
+## Step 3: Protect Pages (UI Guard)
+
+Check the role in client components via `useAuth`:
+
+```tsx
+'use client';
+
+import { useAuth } from '@/features/auth/context/AuthContext';
+
+export function AdminPanel() {
+  const { user } = useAuth();
+
+  if (user?.role !== 'admin') {
+    return null;
+  }
+
+  return <div>{/* Admin content */}</div>;
+}
+```
+
+For full page protection, use middleware (see `add-middleware` skill):
+
+```typescript
+const moderatorRoutes = ['/moderation'];
+
+if (moderatorRoutes.some((r) => pathname.startsWith(r))) {
+  if (!isAuthenticated) { /* redirect to sign-in */ }
+  if (!['admin', 'moderator'].includes(session?.role || '')) {
+    return NextResponse.redirect(new URL('/dashboard', request.url));
+  }
+}
+```
+
+## Step 4: Admin UI for Role Management
+
+Create an admin route to update user roles:
+
+```typescript
+// src/app/api/protected/admin/users/[id]/role/route.ts
+import { handleApiError, withRole, type AuthenticatedRequest } from '@/lib/mars';
+import { prisma } from '@/lib/prisma';
+import { ROLES } from '@/features/admin/types';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const updateRoleSchema = z.object({
+  role: z.enum(ROLES),
+});
+
+export const PATCH = withRole(['admin'], async (request: AuthenticatedRequest, context) => {
+  try {
+    const { id } = await context.params;
+    const { role } = updateRoleSchema.parse(await request.json());
+
+    // Prevent admins from demoting themselves
+    if (id === request.session.userId) {
+      return NextResponse.json({ error: 'Cannot change your own role' }, { status: 400 });
+    }
+
+    const user = await prisma.user.update({
+      where: { id },
+      data: { role },
+      select: { id: true, email: true, role: true },
+    });
+
+    return NextResponse.json(user);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/admin/users/[id]/role' });
+  }
+});
+```
+
+## Step 5: Seed the Admin User
+
+Update `prisma/seed.ts` to create users with the new role:
+
+```typescript
+await prisma.user.create({
+  data: {
+    email: 'moderator@example.com',
+    name: 'Moderator',
+    password: await hash('mod123456', 12),
+    role: 'moderator',
+    emailVerified: new Date(),
+  },
+});
+```
+
+## Security Notes
+
+- **`withRole` always checks the database**, not the JWT claim. This means role changes take effect immediately.
+- **The middleware role check is a UI guard only.** The real security boundary is `withRole` in the API layer.
+- **Never trust client-reported roles.** The `user.role` from `useAuth()` is for UI display only.
+- **Log role changes** for audit purposes.
+
+## Checklist
+
+- [ ] Role added to `ROLES` constant and `Role` type
+- [ ] Role hierarchy updated (if applicable)
+- [ ] API routes protected with `withRole`
+- [ ] UI guards added for role-specific pages
+- [ ] Middleware updated for new role-specific route groups
+- [ ] Admin API route for role management
+- [ ] Self-demotion prevented
+- [ ] Seed data updated with new role users
+- [ ] Role changes logged for auditing

package/template/.cursor/skills/add-server-action/SKILL.md

@@ -0,0 +1,167 @@
+# Skill: Add a Server Action
+
+Create a Next.js Server Action for form submissions and mutations, following MARS conventions for auth, validation, and error handling.
+
+## When to Use
+
+Use this skill when the user asks to add a form submission handler, a mutation that doesn't need a full API route, or wants to use React Server Actions.
+
+## When to Use Server Actions vs API Routes
+
+| Use Server Actions | Use API Routes |
+|---|---|
+| Form submissions from pages | External API consumers |
+| Simple mutations from client components | Webhooks |
+| Progressive enhancement (works without JS) | Complex request/response patterns |
+| Single-use handlers tied to a specific page | Shared endpoints used by multiple clients |
+
+## Directory
+
+Server actions live in the feature's server directory:
+
+```
+src/features/<name>/server/actions.ts
+```
+
+## Template: Basic Server Action
+
+```typescript
+'use server';
+
+import { prisma } from '@/lib/prisma';
+import { verifySessionForAPI } from '@/lib/mars';
+import { z } from 'zod';
+
+const updateProfileSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100),
+});
+
+interface ActionResult {
+  success: boolean;
+  error?: string;
+}
+
+export async function updateProfile(formData: FormData): Promise<ActionResult> {
+  const session = await verifySessionForAPI();
+  if (!session) {
+    return { success: false, error: 'Authentication required' };
+  }
+
+  const raw = {
+    name: formData.get('name'),
+  };
+
+  const parsed = updateProfileSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.errors[0].message };
+  }
+
+  try {
+    await prisma.user.update({
+      where: { id: session.userId },
+      data: { name: parsed.data.name },
+    });
+
+    return { success: true };
+  } catch {
+    return { success: false, error: 'Failed to update profile. Please try again.' };
+  }
+}
+```
+
+## Template: With Revalidation
+
+```typescript
+'use server';
+
+import { prisma } from '@/lib/prisma';
+import { verifySessionForAPI } from '@/lib/mars';
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+const createItemSchema = z.object({
+  title: z.string().min(1).max(200),
+  description: z.string().max(1000).optional(),
+});
+
+export async function createItem(formData: FormData) {
+  const session = await verifySessionForAPI();
+  if (!session) {
+    return { success: false, error: 'Authentication required' };
+  }
+
+  const parsed = createItemSchema.safeParse({
+    title: formData.get('title'),
+    description: formData.get('description'),
+  });
+
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.errors[0].message };
+  }
+
+  try {
+    await prisma.item.create({
+      data: { ...parsed.data, userId: session.userId },
+    });
+
+    revalidatePath('/dashboard');
+    return { success: true };
+  } catch {
+    return { success: false, error: 'Failed to create item' };
+  }
+}
+```
+
+## Using in a Client Component
+
+```tsx
+'use client';
+
+import { Button, Input } from '@mars-stack/ui';
+import { useActionState } from 'react';
+import { updateProfile } from '@/features/settings/server/actions';
+
+export function ProfileForm({ currentName }: { currentName: string }) {
+  const [state, formAction, isPending] = useActionState(updateProfile, {
+    success: false,
+    error: undefined,
+  });
+
+  return (
+    <form action={formAction} className="space-y-4">
+      <Input
+        name="name"
+        label="Display Name"
+        defaultValue={currentName}
+        error={state.error}
+      />
+      <Button type="submit" disabled={isPending}>
+        {isPending ? 'Saving...' : 'Save Changes'}
+      </Button>
+      {state.success && (
+        <p className="text-sm text-text-success">Profile updated successfully.</p>
+      )}
+    </form>
+  );
+}
+```
+
+## Rules
+
+- **Always verify the session** at the top of every server action. Server actions are callable from the client.
+- **Always validate input** with Zod. Never trust `formData` values.
+- **Return a result object** (`{ success, error }`) instead of throwing -- this gives the client a clean way to handle errors.
+- **Scope database queries by `session.userId`** -- never use a userId from formData for authorization.
+- **Use `revalidatePath` or `revalidateTag`** to refresh cached data after mutations.
+- **Mark the file with `'use server'`** at the top (not inline on individual functions).
+
+## Checklist
+
+- [ ] File marked with `'use server'` at top
+- [ ] Session verified before any database access
+- [ ] Input validated with Zod `.safeParse()`
+- [ ] Database queries scoped by `session.userId`
+- [ ] Returns `{ success, error }` result object
+- [ ] `revalidatePath` called after mutations
+- [ ] Client component uses `useActionState` for form binding
+- [ ] No sensitive data in the return value

package/template/.cursor/skills/add-webhook/SKILL.md

@@ -0,0 +1,192 @@
+# Skill: Add a Webhook Handler
+
+Create an incoming webhook endpoint that securely receives and processes external service callbacks (e.g., Stripe, SendGrid, GitHub).
+
+## When to Use
+
+Use this skill when the user needs to handle webhooks from a third-party service, payment processor, or external system.
+
+## Key Principles
+
+1. **Verify signatures** -- always validate the webhook signature before processing.
+2. **Idempotent** -- handle duplicate deliveries gracefully (use event IDs).
+3. **Fast response** -- return 200 quickly; do heavy processing after responding or in a background job.
+4. **No auth wrappers** -- webhooks are public endpoints authenticated by signature, not session.
+
+## Directory
+
+Webhooks live at `src/app/api/webhooks/<service>/route.ts` (outside `/protected/`).
+
+## Template: Stripe Webhook
+
+```typescript
+import { handleApiError, apiLogger } from '@/lib/mars';
+import { prisma } from '@/lib/prisma';
+import { headers } from 'next/headers';
+import { NextResponse } from 'next/server';
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',
+});
+
+const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.text();
+    const headersList = await headers();
+    const signature = headersList.get('stripe-signature');
+
+    if (!signature) {
+      return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
+    }
+
+    let event: Stripe.Event;
+    try {
+      event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
+    } catch {
+      apiLogger.warn('Webhook signature verification failed');
+      return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
+    }
+
+    apiLogger.info({ eventType: event.type, eventId: event.id }, 'Webhook received');
+
+    switch (event.type) {
+      case 'checkout.session.completed':
+        await handleCheckoutCompleted(event.data.object as Stripe.Checkout.Session);
+        break;
+      case 'customer.subscription.updated':
+        await handleSubscriptionUpdated(event.data.object as Stripe.Subscription);
+        break;
+      case 'customer.subscription.deleted':
+        await handleSubscriptionDeleted(event.data.object as Stripe.Subscription);
+        break;
+      default:
+        apiLogger.info({ eventType: event.type }, 'Unhandled webhook event type');
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/webhooks/stripe' });
+  }
+}
+
+async function handleCheckoutCompleted(session: Stripe.Checkout.Session) {
+  // Idempotency: check if already processed
+  // Update database with payment/subscription info
+}
+
+async function handleSubscriptionUpdated(subscription: Stripe.Subscription) {
+  // Update subscription status in database
+}
+
+async function handleSubscriptionDeleted(subscription: Stripe.Subscription) {
+  // Mark subscription as cancelled
+}
+```
+
+## Template: Generic Webhook (HMAC Signature)
+
+For services that use HMAC-SHA256 signatures:
+
+```typescript
+import { handleApiError, apiLogger } from '@/lib/mars';
+import { createHmac, timingSafeEqual } from 'crypto';
+import { NextResponse } from 'next/server';
+
+const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET_<SERVICE>!;
+
+function verifySignature(payload: string, signature: string): boolean {
+  const expected = createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
+  try {
+    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.text();
+    const signature = request.headers.get('x-webhook-signature');
+
+    if (!signature || !verifySignature(body, signature)) {
+      apiLogger.warn('Webhook signature verification failed');
+      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+    }
+
+    const payload = JSON.parse(body);
+
+    apiLogger.info({ eventType: payload.type }, 'Webhook received');
+
+    // Process the event...
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/webhooks/<service>' });
+  }
+}
+```
+
+## Security Rules
+
+- **Always use `timingSafeEqual`** for signature comparison (never `===`).
+- **Read the raw body** with `request.text()`, not `request.json()`, before verifying the signature.
+- **Never trust the payload** until the signature is verified.
+- **Log the event type and ID** for debugging, never log the full payload (may contain PII).
+- **Add the webhook URL to CSRF exclusions** in middleware (webhooks don't carry CSRF tokens).
+
+## Middleware Update
+
+Exclude the webhook route from CSRF validation in `src/middleware.ts`:
+
+```typescript
+// In the middleware, webhook routes bypass CSRF
+if (pathname.startsWith('/api/webhooks/')) {
+  return NextResponse.next();
+}
+```
+
+## Idempotency Pattern
+
+```typescript
+async function processEvent(eventId: string, handler: () => Promise<void>) {
+  const existing = await prisma.webhookEvent.findUnique({
+    where: { externalId: eventId },
+  });
+
+  if (existing) {
+    apiLogger.info({ eventId }, 'Duplicate webhook event, skipping');
+    return;
+  }
+
+  await prisma.$transaction(async (tx) => {
+    await tx.webhookEvent.create({
+      data: { externalId: eventId, processedAt: new Date() },
+    });
+    await handler();
+  });
+}
+```
+
+## Environment Variables
+
+Add webhook secrets to `src/core/env/index.ts` in `buildEnvSchema()`:
+
+```typescript
+base.STRIPE_WEBHOOK_SECRET = z.string().min(1).optional();
+```
+
+## Checklist
+
+- [ ] Route at `src/app/api/webhooks/<service>/route.ts`
+- [ ] Signature verification before processing
+- [ ] Constant-time comparison (`timingSafeEqual`) for signatures
+- [ ] Raw body read (`request.text()`) before signature check
+- [ ] Event type switch with specific handlers
+- [ ] Idempotency check (prevent duplicate processing)
+- [ ] Logger used (not `console.log`)
+- [ ] Excluded from CSRF in middleware
+- [ ] Webhook secret added to env schema
+- [ ] `handleApiError` in catch block