@mars-stack/cli 0.2.0 → 0.2.2

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

@@ -0,0 +1,135 @@
+# Skill: Add Middleware Logic
+
+Extend the Next.js middleware to add new route protection, redirects, or request processing.
+
+## When to Use
+
+Use this skill when the user asks to add route guards, redirects, header injection, geo-based routing, A/B testing at the edge, or any request-level logic.
+
+## Architecture
+
+MARS uses a single `src/middleware.ts` file. Next.js only supports one middleware -- all logic lives here.
+
+## Current Middleware Structure
+
+The middleware runs in order:
+
+1. **Coming-soon mode** -- redirects all non-API traffic to `/coming-soon` when `COMING_SOON=true`.
+2. **CSRF skip** -- allows `/api/csrf` through without validation.
+3. **CSRF validation** -- validates CSRF token on protected API routes and auth endpoints.
+4. **Session check** -- decrypts the session cookie.
+5. **Auth redirects** -- redirects authenticated users away from auth pages, unauthenticated users to sign-in.
+6. **Admin guard** -- redirects non-admin users away from admin routes.
+
+## Adding a New Route Guard
+
+### Step 1: Define the Routes
+
+Add your route constants at the top of the file:
+
+```typescript
+const premiumRoutes = ['/pro', '/analytics'];
+```
+
+### Step 2: Add the Check
+
+Insert your logic after the session check (after line ~50) but before the final `NextResponse.next()`:
+
+```typescript
+// Premium route guard
+if (premiumRoutes.some((route) => pathname.startsWith(route))) {
+  if (!isAuthenticated) {
+    const url = new URL(routes.signIn, request.url);
+    url.searchParams.set('callbackUrl', encodeURI(request.url));
+    return NextResponse.redirect(url);
+  }
+  // Optional: check subscription status via a lightweight cookie or header
+}
+```
+
+### Step 3: Update the Matcher
+
+Add the new paths to the `config.matcher` array:
+
+```typescript
+export const config = {
+  matcher: [
+    // ... existing matchers
+    '/pro/:path*',
+    '/analytics/:path*',
+  ],
+};
+```
+
+## Common Patterns
+
+### Adding Response Headers
+
+```typescript
+const response = NextResponse.next();
+response.headers.set('X-Frame-Options', 'DENY');
+response.headers.set('X-Content-Type-Options', 'nosniff');
+response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+return response;
+```
+
+### Maintenance Mode (like coming-soon but for specific routes)
+
+```typescript
+const maintenanceRoutes = ['/billing'];
+const isMaintenanceMode = process.env.MAINTENANCE_MODE === 'true';
+
+if (isMaintenanceMode && maintenanceRoutes.some((r) => pathname.startsWith(r))) {
+  return NextResponse.redirect(new URL('/maintenance', request.url));
+}
+```
+
+### Geo-Based Redirects
+
+```typescript
+const country = request.geo?.country || request.headers.get('x-vercel-ip-country');
+
+if (country === 'GB' && pathname === '/pricing') {
+  return NextResponse.rewrite(new URL('/pricing/gb', request.url));
+}
+```
+
+### Rate Limiting at the Edge (lightweight)
+
+For heavy rate limiting, use `@mars-stack/core/rate-limit` in API routes. For lightweight edge protection:
+
+```typescript
+// Simple bot detection
+const userAgent = request.headers.get('user-agent') || '';
+if (!userAgent || userAgent.length < 10) {
+  return new NextResponse('Forbidden', { status: 403 });
+}
+```
+
+## Rules
+
+- **Keep middleware fast.** It runs on every matched request. No database calls, no heavy computation.
+- **Use cookies or headers** for edge-level checks, not database queries.
+- **Database-backed authorization** belongs in API route wrappers (`withAuth`, `withRole`), not middleware.
+- **The `config.matcher`** must include every route the middleware needs to process. Unmatched routes skip middleware entirely.
+- **Order matters.** CSRF validation must happen before route guards. Session check must happen before auth redirects.
+
+## Excluding Routes from CSRF
+
+If you add a new public API endpoint (like a webhook), exclude it from CSRF validation:
+
+```typescript
+// At the top of the middleware function
+if (pathname.startsWith('/api/webhooks/')) {
+  return NextResponse.next();
+}
+```
+
+## Checklist
+
+- [ ] Logic added in the correct order within middleware
+- [ ] Route patterns added to `config.matcher`
+- [ ] New route constants defined at top of file
+- [ ] No database calls in middleware (use cookies/headers)
+- [ ] CSRF exclusions added for public API endpoints
+- [ ] Tested with authenticated and unauthenticated users

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

@@ -0,0 +1,151 @@
+# Skill: Add a Page
+
+Create a new Next.js page following MARS conventions for routing, layout, and component usage.
+
+## When to Use
+
+Use this skill when the user asks to add a new page, screen, view, or route to the application.
+
+## Decision: Public or Protected?
+
+| Type | Location | Layout | Auth |
+|------|----------|--------|------|
+| Public | `src/app/(public)/<name>/page.tsx` | Public layout | No auth required |
+| Auth | `src/app/(auth)/<name>/page.tsx` | Centred card layout | No auth (login/signup flows) |
+| Protected | `src/app/(protected)/<name>/page.tsx` | App layout (sidebar/nav) | Requires session |
+
+The middleware at `src/middleware.ts` handles auth redirects automatically based on route groups.
+
+## Protected Page Template
+
+```tsx
+import { Card, CardHeader, CardBody, H1, Paragraph } from '@mars-stack/ui';
+
+export default function WidgetsPage() {
+  return (
+    <div className="mx-auto max-w-4xl space-y-6 p-6">
+      <div>
+        <H1>Widgets</H1>
+        <Paragraph className="text-text-secondary">
+          Manage your widgets.
+        </Paragraph>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <h2 className="text-lg font-semibold text-text-primary">All Widgets</h2>
+        </CardHeader>
+        <CardBody>
+          {/* Content here */}
+        </CardBody>
+      </Card>
+    </div>
+  );
+}
+```
+
+## Loading State
+
+Create `loading.tsx` beside the page for Suspense:
+
+```tsx
+import { Spinner } from '@mars-stack/ui';
+
+export default function Loading() {
+  return (
+    <div className="flex min-h-[50vh] items-center justify-center">
+      <Spinner size="lg" />
+    </div>
+  );
+}
+```
+
+## Client Components with Data Fetching
+
+For pages that need client-side data, create a client component in the feature module:
+
+```tsx
+// src/features/widgets/components/WidgetList.tsx
+'use client';
+
+import { Card, CardBody, Spinner, Badge, EmptyState } from '@mars-stack/ui';
+import { useEffect, useState } from 'react';
+import type { Widget } from '@/features/widgets/types';
+
+export function WidgetList() {
+  const [widgets, setWidgets] = useState<Widget[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/protected/widgets')
+      .then((res) => res.json())
+      .then(setWidgets)
+      .finally(() => setLoading(false));
+  }, []);
+
+  if (loading) return <Spinner size="md" />;
+  if (widgets.length === 0) return <EmptyState title="No widgets yet" description="Create your first widget to get started." />;
+
+  return (
+    <div className="space-y-3">
+      {widgets.map((widget) => (
+        <Card key={widget.id}>
+          <CardBody className="flex items-center justify-between">
+            <span className="text-text-primary font-medium">{widget.name}</span>
+            <Badge variant="success">{widget.status}</Badge>
+          </CardBody>
+        </Card>
+      ))}
+    </div>
+  );
+}
+```
+
+Then import in the page:
+
+```tsx
+import { WidgetList } from '@/features/widgets/components/WidgetList';
+
+export default function WidgetsPage() {
+  return (
+    <div className="mx-auto max-w-4xl space-y-6 p-6">
+      <H1>Widgets</H1>
+      <WidgetList />
+    </div>
+  );
+}
+```
+
+## Routes Config
+
+Add the new route to `src/config/routes.ts`:
+
+```typescript
+export const routes = {
+  // ... existing routes
+  widgets: '/widgets',
+} as const;
+```
+
+## SEO (Optional)
+
+Export `metadata` for static SEO or `generateMetadata` for dynamic:
+
+```tsx
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Widgets',
+  description: 'Manage your widgets',
+};
+```
+
+## Checklist
+
+- [ ] Correct route group (public / auth / protected)
+- [ ] `loading.tsx` created for Suspense
+- [ ] Components use design system primitives and patterns
+- [ ] All colours use semantic tokens
+- [ ] Route added to `src/config/routes.ts`
+- [ ] SEO metadata exported
+- [ ] Client components live in `src/features/<name>/components/`

package/template/.cursor/skills/add-prisma-model/SKILL.md

@@ -0,0 +1,148 @@
+# Skill: Add a Prisma Model
+
+Add a new database model to the MARS multi-file Prisma schema.
+
+## When to Use
+
+Use this skill when the user asks to add a database table, model, entity, or schema.
+
+## Prerequisites
+
+- Read the existing schema files in `prisma/schema/` to understand current models and relations.
+- Check `prisma/schema/base.prisma` for the datasource and generator configuration.
+
+## Steps
+
+### 1. Create a New Schema File
+
+Add `prisma/schema/<name>.prisma`:
+
+```prisma
+model Invoice {
+  id          String   @id @default(cuid())
+  number      String   @unique
+  amount      Int
+  currency    String   @default("gbp")
+  status      String   @default("draft")
+  userId      String
+  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([userId])
+  @@index([status])
+}
+```
+
+### Key Conventions
+
+- **IDs**: Use `@id @default(cuid())` for primary keys.
+- **Timestamps**: Always include `createdAt` and `updatedAt`.
+- **User relation**: If user-scoped, add `userId String` + `@relation` + `@@index([userId])`.
+- **Cascade deletes**: Use `onDelete: Cascade` for child records owned by a user.
+- **Indexes**: Add `@@index` for columns used in `where` clauses and foreign keys.
+- **Enums**: Prefer string fields with TypeScript union types over Prisma enums (more flexible for migrations).
+- **Naming**: PascalCase for models, camelCase for fields.
+
+### 2. Update the User Model (if user-scoped)
+
+In `prisma/schema/auth.prisma`, add the reverse relation:
+
+```prisma
+model User {
+  // ... existing fields
+  invoices Invoice[]
+}
+```
+
+### 3. Sync the Database
+
+```bash
+yarn db:push          # Development: push schema directly
+yarn db:migrate dev   # With migration history (recommended for teams)
+```
+
+### 4. Create Server Access Functions
+
+In `src/features/<name>/server/`:
+
+```typescript
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+
+export async function findInvoicesByUserId(userId: string) {
+  return prisma.invoice.findMany({
+    where: { userId },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+
+export async function findInvoiceByIdForUser(id: string, userId: string) {
+  return prisma.invoice.findFirst({
+    where: { id, userId },
+  });
+}
+
+export async function createInvoice(userId: string, data: { number: string; amount: number }) {
+  return prisma.invoice.create({
+    data: { ...data, userId },
+  });
+}
+```
+
+**Critical**: Always scope queries by `userId` from the session. Never trust client-provided user IDs.
+
+### 5. Regenerate the Prisma Client
+
+This happens automatically with `db:push`, but if needed:
+
+```bash
+yarn db:generate
+```
+
+## Common Patterns
+
+### Soft Deletes
+```prisma
+model Post {
+  // ...
+  deletedAt DateTime?
+  @@index([deletedAt])
+}
+```
+
+### Polymorphic Relations (via discriminator)
+```prisma
+model Notification {
+  id         String   @id @default(cuid())
+  type       String   // "invoice.paid", "user.invited"
+  resourceId String?  // FK to the related entity
+  userId     String
+  // ...
+}
+```
+
+### Many-to-Many
+```prisma
+model Tag {
+  id    String @id @default(cuid())
+  name  String @unique
+  posts Post[] @relation("PostTags")
+}
+
+model Post {
+  // ...
+  tags Tag[] @relation("PostTags")
+}
+```
+
+## Checklist
+
+- [ ] Schema file created in `prisma/schema/`
+- [ ] cuid IDs, timestamps included
+- [ ] User relation and index added (if user-scoped)
+- [ ] `db:push` or `db:migrate dev` run
+- [ ] Server access functions created with `'server-only'` import
+- [ ] All queries scoped by userId
+- [ ] Reverse relation added to User model if needed

package/template/.cursor/skills/add-protected-resource/SKILL.md

@@ -0,0 +1,192 @@
+# Skill: Add a Protected Resource
+
+Create a user-owned resource with proper ownership verification, ensuring users can only access their own data.
+
+## When to Use
+
+Use this skill when the user asks to add a resource that belongs to a specific user (e.g., "add notes", "add projects", "add invoices").
+
+## Architecture
+
+MARS enforces ownership at the API layer using `withOwnership`. This wrapper:
+1. Authenticates the request (session)
+2. Resolves the resource owner from the database
+3. Compares the resource owner to the authenticated user
+4. Returns 403 if they don't match
+
+## Full Implementation
+
+### Step 1: Prisma Model
+
+```prisma
+// prisma/schema/projects.prisma
+model Project {
+  id          String   @id @default(cuid())
+  name        String
+  description String?
+  status      String   @default("active")
+  userId      String
+  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([userId])
+  @@index([status])
+}
+```
+
+Update `prisma/schema/auth.prisma`:
+```prisma
+model User {
+  // ...existing fields
+  projects Project[]
+}
+```
+
+### Step 2: Server Access Layer
+
+```typescript
+// src/features/projects/server/index.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import type { CreateProjectInput, UpdateProjectInput } from '../validation/schemas';
+
+export async function findProjectsByUser(userId: string) {
+  return prisma.project.findMany({
+    where: { userId },
+    orderBy: { updatedAt: 'desc' },
+  });
+}
+
+export async function findProjectById(id: string) {
+  return prisma.project.findUnique({ where: { id } });
+}
+
+export async function createProject(userId: string, data: CreateProjectInput) {
+  return prisma.project.create({
+    data: { ...data, userId },
+  });
+}
+
+export async function updateProject(id: string, data: UpdateProjectInput) {
+  return prisma.project.update({ where: { id }, data });
+}
+
+export async function deleteProject(id: string) {
+  return prisma.project.delete({ where: { id } });
+}
+```
+
+### Step 3: API Routes with Ownership
+
+```typescript
+// src/app/api/protected/projects/[id]/route.ts
+import { handleApiError, withOwnership, type AuthenticatedRequest } from '@/lib/mars';
+import { findProjectById, updateProject, deleteProject } from '@/features/projects/server';
+import { projectSchemas } from '@/features/projects/validation/schemas';
+import { NextResponse } from 'next/server';
+
+async function getProjectOwner(
+  _request: AuthenticatedRequest,
+  context: { params: Promise<{ [key: string]: string }> },
+): Promise<string | null> {
+  const { id } = await context.params;
+  const project = await findProjectById(id);
+  return project?.userId ?? null;
+}
+
+export const GET = withOwnership(getProjectOwner, async (_request, context) => {
+  try {
+    const { id } = await context.params;
+    const project = await findProjectById(id);
+    return NextResponse.json(project);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/projects/[id]' });
+  }
+});
+
+export const PATCH = withOwnership(getProjectOwner, async (request, context) => {
+  try {
+    const { id } = await context.params;
+    const body = projectSchemas.update.parse(await request.json());
+    const project = await updateProject(id, body);
+    return NextResponse.json(project);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/projects/[id]' });
+  }
+});
+
+export const DELETE = withOwnership(getProjectOwner, async (_request, context) => {
+  try {
+    const { id } = await context.params;
+    await deleteProject(id);
+    return NextResponse.json({ message: 'Project deleted' });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/projects/[id]' });
+  }
+});
+```
+
+### Step 4: Collection Route (no ownership check needed)
+
+```typescript
+// src/app/api/protected/projects/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { findProjectsByUser, createProject } from '@/features/projects/server';
+import { projectSchemas } from '@/features/projects/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const projects = await findProjectsByUser(request.session.userId);
+    return NextResponse.json(projects);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/projects' });
+  }
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const body = projectSchemas.create.parse(await request.json());
+    const project = await createProject(request.session.userId, body);
+    return NextResponse.json(project, { status: 201 });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/projects' });
+  }
+});
+```
+
+## How `withOwnership` Works
+
+```
+Client: PATCH /api/protected/projects/abc123
+  ↓
+withOwnership calls getProjectOwner("abc123")
+  ↓ returns "user_xyz" (the project's userId)
+  ↓
+Compares "user_xyz" with request.session.userId
+  ↓
+✅ Match → handler runs
+❌ Mismatch → 403 Forbidden
+❌ null (not found) → 404 Not Found
+```
+
+## Security Rules
+
+- **Never accept userId from the client** for authorization. Always use `request.session.userId`.
+- **List endpoints don't need `withOwnership`** -- they scope the query by `userId` from the session.
+- **Individual resource endpoints use `withOwnership`** -- they verify the resource belongs to the user.
+- **Admin override**: If admins should access any resource, use `withRole` instead of `withOwnership`.
+- **The ownership resolver fetches from DB** every time -- no caching, no stale data.
+
+## Checklist
+
+- [ ] Prisma model with `userId` field and `@@index([userId])`
+- [ ] `onDelete: Cascade` on the user relation
+- [ ] Server functions scope list queries by `userId`
+- [ ] Individual resource routes use `withOwnership`
+- [ ] Collection routes use `withAuth` / `withAuthNoParams`
+- [ ] Ownership resolver returns `userId` or `null`
+- [ ] No client-provided `userId` used for authorization
+- [ ] `handleApiError` in every catch block