@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-email-verification/SKILL.md

@@ -0,0 +1,333 @@
+# Skill: Configure Email Verification
+
+Set up and customize the email verification flow in a MARS application, including resend logic, expiry, custom pages, and rate limiting.
+
+## When to Use
+
+Use this skill when the user asks to add email verification, customize the verification flow, handle resend logic, change verification token expiry, build a custom verification page, or handle already-verified users.
+
+## Prerequisites
+
+- Email provider configured (see `configure-email` skill)
+- `appConfig.features.emailVerification` set to `true` in `src/config/app.config.ts`
+- Prisma schema includes a `User` model with `emailVerified` and `emailVerifyToken` fields
+
+## Architecture
+
+MARS email verification uses a token-based flow:
+1. User signs up → server generates a random token, stores it hashed in DB, sends raw token via email
+2. User clicks link → server hashes the incoming token, compares against DB, marks user verified
+3. Token has a configurable expiry; resend requests are rate-limited
+
+The verification service lives in `src/features/auth/server/verification.ts` and all token comparisons use constant-time equality.
+
+## Step 1: Prisma Schema Fields
+
+Ensure the `User` model in `prisma/schema/auth.prisma` includes:
+
+```prisma
+model User {
+  id                  String    @id @default(cuid())
+  email               String    @unique
+  emailVerified       Boolean   @default(false)
+  emailVerifyToken    String?
+  emailVerifyExpires  DateTime?
+  // ... other fields
+}
+```
+
+Run `yarn db:push` after changes.
+
+## Step 2: Verification Configuration
+
+Add verification settings to `src/config/app.config.ts`:
+
+```typescript
+features: {
+  emailVerification: true,
+},
+auth: {
+  verification: {
+    tokenExpiryHours: 24,
+    resendCooldownMinutes: 2,
+    maxResendAttempts: 5,
+  },
+},
+```
+
+## Step 3: Token Generation and Verification Service
+
+```typescript
+// src/features/auth/server/verification.ts
+import 'server-only';
+
+import { randomBytes, createHash } from 'crypto';
+import { prisma } from '@/lib/prisma';
+import { sendEmail } from '@/lib/mars';
+import { appConfig } from '@/config/app.config';
+import { constantTimeEqual } from '@/lib/mars';
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+export async function generateVerificationToken(userId: string): Promise<string> {
+  const rawToken = randomBytes(32).toString('hex');
+  const hashedToken = hashToken(rawToken);
+  const expiryHours = appConfig.auth.verification.tokenExpiryHours;
+
+  await prisma.user.update({
+    where: { id: userId },
+    data: {
+      emailVerifyToken: hashedToken,
+      emailVerifyExpires: new Date(Date.now() + expiryHours * 60 * 60 * 1000),
+    },
+  });
+
+  return rawToken;
+}
+
+export async function verifyEmail(token: string): Promise<{ success: boolean; error?: string }> {
+  const hashedToken = hashToken(token);
+
+  const user = await prisma.user.findFirst({
+    where: { emailVerifyToken: hashedToken },
+  });
+
+  if (!user) {
+    return { success: false, error: 'Invalid verification token' };
+  }
+
+  if (user.emailVerified) {
+    return { success: false, error: 'Email already verified' };
+  }
+
+  if (user.emailVerifyExpires && user.emailVerifyExpires < new Date()) {
+    return { success: false, error: 'Verification token has expired' };
+  }
+
+  await prisma.user.update({
+    where: { id: user.id },
+    data: {
+      emailVerified: true,
+      emailVerifyToken: null,
+      emailVerifyExpires: null,
+    },
+  });
+
+  return { success: true };
+}
+
+export async function sendVerificationEmail(userId: string, email: string): Promise<void> {
+  const token = await generateVerificationToken(userId);
+  const baseUrl = process.env.APP_URL || 'http://localhost:3000';
+  const verifyUrl = `${baseUrl}/auth/verify-email?token=${token}`;
+
+  await sendEmail({
+    to: email,
+    subject: `Verify your email for ${appConfig.name}`,
+    text: `Verify your email by visiting: ${verifyUrl}\n\nThis link expires in ${appConfig.auth.verification.tokenExpiryHours} hours.`,
+    html: `
+      <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
+        <h2>Verify your email</h2>
+        <p>Click the button below to verify your email address:</p>
+        <div style="text-align: center; margin: 30px 0;">
+          <a href="${verifyUrl}" style="background-color: #2563eb; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">
+            Verify Email
+          </a>
+        </div>
+        <p style="color: #6b7280; font-size: 14px;">This link expires in ${appConfig.auth.verification.tokenExpiryHours} hours.</p>
+      </div>
+    `,
+  });
+}
+```
+
+## Step 4: Verification API Route
+
+```typescript
+// src/app/api/auth/verify-email/route.ts
+import { handleApiError } from '@/lib/mars';
+import { verifyEmail } from '@/features/auth/server/verification';
+import { NextResponse, type NextRequest } from 'next/server';
+import { z } from 'zod';
+
+const verifySchema = z.object({
+  token: z.string().min(1, 'Token is required'),
+});
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const { token } = verifySchema.parse({ token: searchParams.get('token') });
+
+    const result = await verifyEmail(token);
+
+    if (!result.success) {
+      return NextResponse.redirect(
+        new URL(`/auth/verify-email?error=${encodeURIComponent(result.error!)}`, request.url),
+      );
+    }
+
+    return NextResponse.redirect(new URL('/auth/verify-email?success=true', request.url));
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/auth/verify-email' });
+  }
+}
+```
+
+## Step 5: Resend Verification Endpoint
+
+```typescript
+// src/app/api/auth/resend-verification/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { checkRateLimit, RATE_LIMITS } from '@/lib/core/rate-limit';
+import { sendVerificationEmail } from '@/features/auth/server/verification';
+import { prisma } from '@/lib/prisma';
+import { NextResponse } from 'next/server';
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const userId = request.session.userId;
+
+    await checkRateLimit(`resend-verify:${userId}`, {
+      maxAttempts: 5,
+      windowMs: 10 * 60 * 1000, // 10 minutes
+    });
+
+    const user = await prisma.user.findUnique({ where: { id: userId } });
+
+    if (!user) {
+      return NextResponse.json({ error: 'User not found' }, { status: 404 });
+    }
+
+    if (user.emailVerified) {
+      return NextResponse.json({ error: 'Email already verified' }, { status: 400 });
+    }
+
+    await sendVerificationEmail(userId, user.email);
+
+    return NextResponse.json({ message: 'Verification email sent' });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/auth/resend-verification' });
+  }
+});
+```
+
+## Step 6: Verification Page
+
+```typescript
+// src/app/auth/verify-email/page.tsx
+'use client';
+
+import { useSearchParams } from 'next/navigation';
+import { useState } from 'react';
+
+export default function VerifyEmailPage() {
+  const searchParams = useSearchParams();
+  const success = searchParams.get('success') === 'true';
+  const error = searchParams.get('error');
+  const [resending, setResending] = useState(false);
+  const [resendMessage, setResendMessage] = useState('');
+
+  async function handleResend() {
+    setResending(true);
+    try {
+      const res = await fetch('/api/auth/resend-verification', { method: 'POST' });
+      const data = await res.json();
+
+      if (!res.ok) {
+        setResendMessage(data.error || 'Failed to resend');
+      } else {
+        setResendMessage('Verification email sent! Check your inbox.');
+      }
+    } catch {
+      setResendMessage('Something went wrong. Try again later.');
+    } finally {
+      setResending(false);
+    }
+  }
+
+  if (success) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="text-center">
+          <h1 className="text-2xl font-bold text-content-primary">Email Verified!</h1>
+          <p className="mt-2 text-content-secondary">Your email has been verified. You can now access all features.</p>
+          <a href="/dashboard" className="mt-4 inline-block text-interactive-primary hover:underline">
+            Go to Dashboard
+          </a>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold text-content-primary">Verify Your Email</h1>
+        {error && <p className="mt-2 text-status-error">{decodeURIComponent(error)}</p>}
+        <p className="mt-2 text-content-secondary">
+          Check your inbox for a verification link. Didn&apos;t receive it?
+        </p>
+        <button
+          onClick={handleResend}
+          disabled={resending}
+          className="mt-4 rounded-md bg-interactive-primary px-4 py-2 text-white hover:bg-interactive-primary-hover disabled:opacity-50"
+        >
+          {resending ? 'Sending...' : 'Resend Verification Email'}
+        </button>
+        {resendMessage && <p className="mt-2 text-sm text-content-secondary">{resendMessage}</p>}
+      </div>
+    </div>
+  );
+}
+```
+
+## Step 7: Gate Features Behind Verification
+
+Create a helper to check verification status:
+
+```typescript
+// src/features/auth/server/index.ts
+export async function requireVerifiedEmail(userId: string): Promise<void> {
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { emailVerified: true },
+  });
+
+  if (!user?.emailVerified) {
+    throw new ApiError(403, 'Email verification required');
+  }
+}
+```
+
+Use in protected routes:
+
+```typescript
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  await requireVerifiedEmail(request.session.userId);
+  // ... proceed with logic
+});
+```
+
+## Testing
+
+1. Sign up with a new account using `console` email provider — check terminal for the verification link.
+2. Click the link — verify the user is marked as verified in the database.
+3. Try clicking again — should show "already verified" message.
+4. Wait for expiry (or manually set `emailVerifyExpires` to the past) — should show "expired" error.
+5. Test resend rate limiting — send more than 5 requests in 10 minutes, verify the 6th is rejected.
+
+## Checklist
+
+- [ ] Prisma schema updated with `emailVerifyToken` and `emailVerifyExpires` fields
+- [ ] Verification config added to `app.config.ts`
+- [ ] Token generation uses `randomBytes` and stores hashed token
+- [ ] Verification route validates and clears token on success
+- [ ] Resend endpoint is rate-limited and checks if already verified
+- [ ] Verification page handles success, error, and resend states
+- [ ] Auth routes call `sendVerificationEmail` on signup
+- [ ] Feature gate helper `requireVerifiedEmail` available
+- [ ] Tokens use constant-time comparison
+- [ ] `db:push` run after schema changes

package/template/.cursor/skills/configure-feature-flags/SKILL.md

@@ -0,0 +1,361 @@
+# Skill: Configure Feature Flags
+
+Set up a runtime feature flag system with environment-based overrides, server-side checks, client-side context, and gradual rollout support.
+
+## When to Use
+
+Use this skill when the user asks to add feature flags, feature toggles, gradual rollout, A/B testing, canary releases, or runtime feature gating.
+
+## Prerequisites
+
+- Read `src/config/app.config.ts` to understand the current feature flag structure.
+- Read `src/lib/mars.ts` to check available core exports.
+
+## How Feature Flags Work in Mars
+
+Mars uses a layered feature flag system:
+
+1. **Build-time flags** — `appConfig.features.*` in `app.config.ts` (static, checked at scaffold time)
+2. **Runtime flags** — Environment variable overrides that can change without redeployment
+3. **User-level flags** — Database-driven flags for per-user or percentage-based rollouts
+
+## Step 1: Define Flag Schema
+
+Add new flags to the app config type and defaults:
+
+```typescript
+// src/config/app.config.ts — extend the features block
+export const appConfig = {
+  features: {
+    // ... existing flags
+    newDashboard: false,
+    betaSearch: false,
+    aiAssistant: false,
+  },
+  // ...
+} as const;
+```
+
+## Step 2: Create the Feature Flags Service
+
+```typescript
+// src/features/feature-flags/server/index.ts
+import 'server-only';
+
+import { appConfig } from '@/config/app.config';
+import { prisma } from '@/lib/prisma';
+
+type FeatureFlag = keyof typeof appConfig.features;
+
+/**
+ * Check if a feature is enabled. Resolution order:
+ * 1. Environment variable override: FEATURE_FLAG_{SCREAMING_SNAKE} = "true" | "false"
+ * 2. User-level flag from database (if userId provided)
+ * 3. Percentage rollout from database (if userId provided)
+ * 4. Static default from appConfig.features
+ */
+export async function isFeatureEnabled(
+  flag: FeatureFlag,
+  userId?: string,
+): Promise<boolean> {
+  const envKey = `FEATURE_FLAG_${toScreamingSnake(flag)}`;
+  const envValue = process.env[envKey];
+  if (envValue === 'true') return true;
+  if (envValue === 'false') return false;
+
+  if (userId) {
+    const userFlag = await prisma.featureFlag.findUnique({
+      where: { flag_userId: { flag, userId } },
+    });
+    if (userFlag) return userFlag.enabled;
+
+    const rollout = await prisma.featureFlagRollout.findUnique({
+      where: { flag },
+    });
+    if (rollout) {
+      return isInRolloutPercentage(userId, rollout.percentage);
+    }
+  }
+
+  return appConfig.features[flag] ?? false;
+}
+
+export async function getEnabledFlags(userId?: string): Promise<Record<string, boolean>> {
+  const flags = Object.keys(appConfig.features) as FeatureFlag[];
+  const results: Record<string, boolean> = {};
+
+  for (const flag of flags) {
+    results[flag] = await isFeatureEnabled(flag, userId);
+  }
+
+  return results;
+}
+
+function toScreamingSnake(str: string): string {
+  return str.replace(/([A-Z])/g, '_$1').toUpperCase();
+}
+
+function isInRolloutPercentage(userId: string, percentage: number): boolean {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) {
+    hash = (hash * 31 + userId.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash % 100) < percentage;
+}
+```
+
+## Step 3: Prisma Schema
+
+```prisma
+// prisma/schema/feature-flags.prisma
+model FeatureFlag {
+  id        String   @id @default(cuid())
+  flag      String
+  userId    String
+  enabled   Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([flag, userId])
+  @@index([flag])
+  @@index([userId])
+}
+
+model FeatureFlagRollout {
+  id         String   @id @default(cuid())
+  flag       String   @unique
+  percentage Int      @default(0)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+}
+```
+
+Run `yarn db:push` to sync.
+
+## Step 4: API Route for Client Flags
+
+```typescript
+// src/app/api/protected/feature-flags/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { getEnabledFlags } from '@/features/feature-flags/server';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const flags = await getEnabledFlags(request.session.userId);
+    return NextResponse.json(flags);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/feature-flags' });
+  }
+});
+```
+
+## Step 5: Client-Side Context and Hook
+
+```tsx
+// src/features/feature-flags/context/FeatureFlagProvider.tsx
+'use client';
+
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
+
+interface FeatureFlagContextValue {
+  flags: Record<string, boolean>;
+  isEnabled: (flag: string) => boolean;
+  loading: boolean;
+}
+
+const FeatureFlagContext = createContext<FeatureFlagContextValue>({
+  flags: {},
+  isEnabled: () => false,
+  loading: true,
+});
+
+export function FeatureFlagProvider({ children }: { children: ReactNode }) {
+  const [flags, setFlags] = useState<Record<string, boolean>>({});
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/protected/feature-flags')
+      .then((res) => res.json())
+      .then(setFlags)
+      .catch(() => {})
+      .finally(() => setLoading(false));
+  }, []);
+
+  const isEnabled = (flag: string) => flags[flag] ?? false;
+
+  return (
+    <FeatureFlagContext value={{ flags, isEnabled, loading }}>
+      {children}
+    </FeatureFlagContext>
+  );
+}
+
+export function useFeatureFlags() {
+  return useContext(FeatureFlagContext);
+}
+
+export function useFeatureFlag(flag: string): boolean {
+  const { isEnabled } = useFeatureFlags();
+  return isEnabled(flag);
+}
+```
+
+Add the provider to the protected layout:
+
+```tsx
+// src/app/(protected)/layout.tsx
+import { FeatureFlagProvider } from '@/features/feature-flags/context/FeatureFlagProvider';
+
+export default function ProtectedLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <FeatureFlagProvider>
+      {children}
+    </FeatureFlagProvider>
+  );
+}
+```
+
+## Step 6: Usage Patterns
+
+### Server-side gating
+
+```typescript
+import { isFeatureEnabled } from '@/features/feature-flags/server';
+
+export const GET = withAuthNoParams(async (request) => {
+  if (!(await isFeatureEnabled('betaSearch', request.session.userId))) {
+    return NextResponse.json({ error: 'Feature not available' }, { status: 403 });
+  }
+  // ... feature logic
+});
+```
+
+### Client-side gating
+
+```tsx
+'use client';
+
+import { useFeatureFlag } from '@/features/feature-flags/context/FeatureFlagProvider';
+
+export function DashboardContent() {
+  const showNewDashboard = useFeatureFlag('newDashboard');
+
+  if (showNewDashboard) {
+    return <NewDashboard />;
+  }
+  return <LegacyDashboard />;
+}
+```
+
+### Environment variable override
+
+```bash
+# Override a flag without redeployment
+FEATURE_FLAG_BETA_SEARCH=true
+FEATURE_FLAG_NEW_DASHBOARD=false
+```
+
+## Step 7: Admin API for Managing Rollouts
+
+```typescript
+// src/app/api/protected/admin/feature-flags/route.ts
+import { handleApiError, withRole, type AuthenticatedRequest } from '@/lib/mars';
+import { prisma } from '@/lib/prisma';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const updateRolloutSchema = z.object({
+  flag: z.string().min(1),
+  percentage: z.number().int().min(0).max(100),
+});
+
+export const GET = withRole(['admin'], async () => {
+  try {
+    const rollouts = await prisma.featureFlagRollout.findMany({
+      orderBy: { flag: 'asc' },
+    });
+    return NextResponse.json(rollouts);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/admin/feature-flags' });
+  }
+});
+
+export const PUT = withRole(['admin'], async (request: AuthenticatedRequest) => {
+  try {
+    const body = updateRolloutSchema.parse(await request.json());
+    const rollout = await prisma.featureFlagRollout.upsert({
+      where: { flag: body.flag },
+      update: { percentage: body.percentage },
+      create: { flag: body.flag, percentage: body.percentage },
+    });
+    return NextResponse.json(rollout);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/admin/feature-flags' });
+  }
+});
+```
+
+## A/B Testing Integration
+
+For A/B testing, combine feature flags with analytics:
+
+```typescript
+import { isFeatureEnabled } from '@/features/feature-flags/server';
+
+export async function getVariant(
+  flag: string,
+  userId: string,
+): Promise<'control' | 'treatment'> {
+  const enabled = await isFeatureEnabled(flag as any, userId);
+  return enabled ? 'treatment' : 'control';
+}
+```
+
+Track variant exposure in your analytics provider when the feature is rendered.
+
+## Testing
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { isFeatureEnabled } from './index';
+
+vi.mock('@/config/app.config', () => ({
+  appConfig: { features: { betaSearch: false, newDashboard: true } },
+}));
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    featureFlag: { findUnique: vi.fn() },
+    featureFlagRollout: { findUnique: vi.fn() },
+  },
+}));
+
+describe('isFeatureEnabled', () => {
+  it('returns static default when no overrides exist', async () => {
+    expect(await isFeatureEnabled('newDashboard')).toBe(true);
+    expect(await isFeatureEnabled('betaSearch')).toBe(false);
+  });
+
+  it('respects environment variable overrides', async () => {
+    process.env.FEATURE_FLAG_BETA_SEARCH = 'true';
+    expect(await isFeatureEnabled('betaSearch')).toBe(true);
+    delete process.env.FEATURE_FLAG_BETA_SEARCH;
+  });
+});
+```
+
+## Checklist
+
+- [ ] Feature flags defined in `appConfig.features`
+- [ ] Server-side `isFeatureEnabled()` with env override support
+- [ ] Prisma models for user-level flags and rollout percentages
+- [ ] API route for client-side flag fetching
+- [ ] `FeatureFlagProvider` context and `useFeatureFlag` hook
+- [ ] Provider added to protected layout
+- [ ] Admin API for managing rollout percentages
+- [ ] Environment variable override convention documented
+- [ ] `db:push` run after schema changes
+- [ ] Tests written for flag resolution logic