@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-oauth/SKILL.md

@@ -0,0 +1,217 @@
+# Skill: Configure OAuth Provider
+
+Add Google OAuth (or other OAuth providers) to the MARS authentication system.
+
+## When to Use
+
+Use this skill when the user asks to add Google sign-in, social login, OAuth, or third-party authentication.
+
+## Prerequisites
+
+- `appConfig.features.auth` is `true`
+- `appConfig.features.googleOAuth` should be set to `true`
+
+## Step 1: Get OAuth Credentials
+
+### Google
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or use existing)
+3. Enable the Google+ API
+4. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
+5. Set authorized redirect URIs: `http://localhost:3000/api/auth/callback/google` and your production URL
+6. Copy Client ID and Client Secret
+
+### Environment Variables
+
+Add to `.env`:
+
+```bash
+GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+GOOGLE_CLIENT_SECRET="your-client-secret"
+```
+
+Update `src/core/env/index.ts` to validate these:
+
+```typescript
+if (appConfig.features.googleOAuth) {
+  base.GOOGLE_CLIENT_ID = z.string().min(1);
+  base.GOOGLE_CLIENT_SECRET = z.string().min(1);
+}
+```
+
+## Step 2: Create the OAuth API Routes
+
+### Initiate flow: `src/app/api/auth/oauth/google/route.ts`
+
+```typescript
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const clientId = process.env.GOOGLE_CLIENT_ID;
+  const redirectUri = `${process.env.APP_URL || 'http://localhost:3000'}/api/auth/callback/google`;
+
+  const params = new URLSearchParams({
+    client_id: clientId!,
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    scope: 'openid email profile',
+    access_type: 'offline',
+    prompt: 'consent',
+  });
+
+  return NextResponse.redirect(`https://accounts.google.com/o/oauth2/v2/auth?${params}`);
+}
+```
+
+### Callback: `src/app/api/auth/callback/google/route.ts`
+
+```typescript
+import { handleApiError, createSession } from '@/lib/mars';
+import { prisma } from '@/lib/prisma';
+import { NextResponse, type NextRequest } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  try {
+    const code = request.nextUrl.searchParams.get('code');
+    if (!code) {
+      return NextResponse.redirect(new URL('/sign-in?error=no_code', request.url));
+    }
+
+    // Exchange code for tokens
+    const tokenResponse = await fetch('https://oauth2.googleapis.com/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        code,
+        client_id: process.env.GOOGLE_CLIENT_ID!,
+        client_secret: process.env.GOOGLE_CLIENT_SECRET!,
+        redirect_uri: `${process.env.APP_URL || 'http://localhost:3000'}/api/auth/callback/google`,
+        grant_type: 'authorization_code',
+      }),
+    });
+
+    const tokens = await tokenResponse.json();
+    if (!tokens.access_token) {
+      return NextResponse.redirect(new URL('/sign-in?error=token_exchange', request.url));
+    }
+
+    // Get user info
+    const userInfoResponse = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+      headers: { Authorization: `Bearer ${tokens.access_token}` },
+    });
+    const profile = await userInfoResponse.json();
+
+    // Find or create user
+    let user = await prisma.user.findUnique({ where: { email: profile.email } });
+
+    if (!user) {
+      user = await prisma.user.create({
+        data: {
+          email: profile.email,
+          name: profile.name,
+          image: profile.picture,
+          emailVerified: new Date(),
+          termsAcceptedAt: new Date(),
+          privacyAcceptedAt: new Date(),
+        },
+      });
+    }
+
+    // Link the OAuth account
+    await prisma.account.upsert({
+      where: {
+        provider_providerAccountId: {
+          provider: 'google',
+          providerAccountId: profile.id,
+        },
+      },
+      update: {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: tokens.expires_in ? Math.floor(Date.now() / 1000) + tokens.expires_in : null,
+      },
+      create: {
+        userId: user.id,
+        provider: 'google',
+        providerAccountId: profile.id,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: tokens.expires_in ? Math.floor(Date.now() / 1000) + tokens.expires_in : null,
+      },
+    });
+
+    // Create session
+    await createSession({
+      id: user.id,
+      email: user.email,
+      name: user.name || user.email,
+      role: user.role,
+      emailVerified: !!user.emailVerified,
+      passwordHash: user.password || '',
+    });
+
+    return NextResponse.redirect(new URL('/dashboard', request.url));
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/auth/callback/google' });
+  }
+}
+```
+
+## Step 3: Add Google Sign-In Button
+
+```tsx
+import { Button } from '@mars-stack/ui';
+
+export function GoogleSignInButton() {
+  return (
+    <a href="/api/auth/oauth/google" className="block">
+      <Button type="button" variant="secondary" className="w-full">
+        <svg className="mr-2 h-5 w-5" viewBox="0 0 24 24">
+          {/* Google G icon SVG path */}
+        </svg>
+        Continue with Google
+      </Button>
+    </a>
+  );
+}
+```
+
+Add to the sign-in and register pages:
+
+```tsx
+{appConfig.features.googleOAuth && (
+  <>
+    <GoogleSignInButton />
+    <Divider label="or" />
+  </>
+)}
+```
+
+## Step 4: Middleware Update
+
+Add the OAuth callback routes to bypass CSRF in `src/middleware.ts`:
+
+```typescript
+if (pathname.startsWith('/api/auth/callback/')) {
+  return NextResponse.next();
+}
+```
+
+## Adding Other Providers
+
+The pattern is identical for GitHub, Discord, etc. Create:
+1. `/api/auth/oauth/<provider>/route.ts` -- initiate
+2. `/api/auth/callback/<provider>/route.ts` -- handle callback
+3. Provider-specific button component
+
+## Checklist
+
+- [ ] OAuth credentials obtained and added to `.env`
+- [ ] Env variables added to validation schema
+- [ ] OAuth initiation route created
+- [ ] Callback route with user creation/linking
+- [ ] Google Sign-In button added to auth pages
+- [ ] Feature flag checked (`appConfig.features.googleOAuth`)
+- [ ] Callback route excluded from CSRF in middleware
+- [ ] Account model used for provider linking (supports multiple providers)

package/template/.cursor/skills/configure-onboarding/SKILL.md

@@ -0,0 +1,483 @@
+# Skill: Configure Onboarding
+
+Set up a multi-step onboarding flow for first-time users in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add user onboarding, a setup wizard, first-time user experience, welcome flow, profile completion, or getting-started steps.
+
+## Prerequisites
+
+- Auth system configured with session management
+- User model exists in Prisma schema
+
+## Architecture
+
+The onboarding system consists of:
+1. **Prisma model** — tracks which steps a user has completed
+2. **Step components** — each step is an isolated component with its own validation
+3. **Progress indicator** — visual stepper showing current position
+4. **Redirect logic** — middleware or layout check redirects incomplete users to onboarding
+5. **Skip/complete** — users can skip optional steps or mark onboarding as complete
+
+## Step 1: Prisma Schema
+
+```prisma
+// prisma/schema/onboarding.prisma
+model OnboardingProgress {
+  id            String   @id @default(cuid())
+  userId        String   @unique
+  completedAt   DateTime?
+  currentStep   Int      @default(0)
+  stepsData     String   @default("{}") // JSON for step-specific data
+  skippedSteps  String   @default("[]") // JSON array of skipped step indices
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+```
+
+Add the relation to the User model and run `yarn db:push`.
+
+## Step 2: Define Onboarding Steps
+
+```typescript
+// src/features/onboarding/config.ts
+export interface OnboardingStep {
+  id: string;
+  title: string;
+  description: string;
+  required: boolean;
+}
+
+export const ONBOARDING_STEPS: OnboardingStep[] = [
+  {
+    id: 'profile',
+    title: 'Complete Your Profile',
+    description: 'Add your name and avatar',
+    required: true,
+  },
+  {
+    id: 'preferences',
+    title: 'Set Preferences',
+    description: 'Choose your notification and display settings',
+    required: false,
+  },
+  {
+    id: 'workspace',
+    title: 'Create Your First Workspace',
+    description: 'Set up a workspace to get started',
+    required: true,
+  },
+  {
+    id: 'invite',
+    title: 'Invite Your Team',
+    description: 'Invite colleagues to collaborate',
+    required: false,
+  },
+];
+```
+
+## Step 3: Server Logic
+
+```typescript
+// src/features/onboarding/server/index.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import { ONBOARDING_STEPS } from '../config';
+
+export async function getOnboardingProgress(userId: string) {
+  let progress = await prisma.onboardingProgress.findUnique({
+    where: { userId },
+  });
+
+  if (!progress) {
+    progress = await prisma.onboardingProgress.create({
+      data: { userId },
+    });
+  }
+
+  return {
+    ...progress,
+    stepsData: JSON.parse(progress.stepsData) as Record<string, unknown>,
+    skippedSteps: JSON.parse(progress.skippedSteps) as number[],
+    totalSteps: ONBOARDING_STEPS.length,
+    isComplete: progress.completedAt !== null,
+  };
+}
+
+export async function updateOnboardingStep(
+  userId: string,
+  stepIndex: number,
+  data?: Record<string, unknown>,
+) {
+  const progress = await prisma.onboardingProgress.findUnique({
+    where: { userId },
+  });
+
+  if (!progress) {
+    throw new Error('Onboarding progress not found');
+  }
+
+  const stepsData = JSON.parse(progress.stepsData);
+  if (data) {
+    stepsData[ONBOARDING_STEPS[stepIndex].id] = data;
+  }
+
+  const nextStep = Math.min(stepIndex + 1, ONBOARDING_STEPS.length);
+  const isLastStep = nextStep === ONBOARDING_STEPS.length;
+
+  await prisma.onboardingProgress.update({
+    where: { userId },
+    data: {
+      currentStep: nextStep,
+      stepsData: JSON.stringify(stepsData),
+      completedAt: isLastStep ? new Date() : null,
+    },
+  });
+
+  return { nextStep, isComplete: isLastStep };
+}
+
+export async function skipOnboardingStep(userId: string, stepIndex: number) {
+  const step = ONBOARDING_STEPS[stepIndex];
+  if (step.required) {
+    throw new Error('Cannot skip a required step');
+  }
+
+  const progress = await prisma.onboardingProgress.findUnique({
+    where: { userId },
+  });
+
+  if (!progress) {
+    throw new Error('Onboarding progress not found');
+  }
+
+  const skippedSteps = JSON.parse(progress.skippedSteps);
+  if (!skippedSteps.includes(stepIndex)) {
+    skippedSteps.push(stepIndex);
+  }
+
+  const nextStep = Math.min(stepIndex + 1, ONBOARDING_STEPS.length);
+  const isLastStep = nextStep === ONBOARDING_STEPS.length;
+
+  await prisma.onboardingProgress.update({
+    where: { userId },
+    data: {
+      currentStep: nextStep,
+      skippedSteps: JSON.stringify(skippedSteps),
+      completedAt: isLastStep ? new Date() : null,
+    },
+  });
+
+  return { nextStep, isComplete: isLastStep };
+}
+
+export async function completeOnboarding(userId: string) {
+  await prisma.onboardingProgress.update({
+    where: { userId },
+    data: { completedAt: new Date() },
+  });
+}
+
+export async function isOnboardingComplete(userId: string): Promise<boolean> {
+  const progress = await prisma.onboardingProgress.findUnique({
+    where: { userId },
+    select: { completedAt: true },
+  });
+  return progress?.completedAt !== null;
+}
+```
+
+## Step 4: API Routes
+
+```typescript
+// src/app/api/protected/onboarding/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { getOnboardingProgress } from '@/features/onboarding/server';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const progress = await getOnboardingProgress(request.session.userId);
+    return NextResponse.json(progress);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/onboarding' });
+  }
+});
+```
+
+```typescript
+// src/app/api/protected/onboarding/step/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { updateOnboardingStep, skipOnboardingStep } from '@/features/onboarding/server';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const stepSchema = z.object({
+  stepIndex: z.number().min(0),
+  action: z.enum(['complete', 'skip']),
+  data: z.record(z.unknown()).optional(),
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const { stepIndex, action, data } = stepSchema.parse(await request.json());
+
+    const result =
+      action === 'skip'
+        ? await skipOnboardingStep(request.session.userId, stepIndex)
+        : await updateOnboardingStep(request.session.userId, stepIndex, data);
+
+    return NextResponse.json(result);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/onboarding/step' });
+  }
+});
+```
+
+## Step 5: Progress Indicator Component
+
+```typescript
+// src/features/onboarding/components/OnboardingProgress.tsx
+'use client';
+
+import { ONBOARDING_STEPS } from '../config';
+
+interface OnboardingProgressProps {
+  currentStep: number;
+  skippedSteps: number[];
+}
+
+export function OnboardingProgressBar({ currentStep, skippedSteps }: OnboardingProgressProps) {
+  return (
+    <div className="flex items-center gap-2">
+      {ONBOARDING_STEPS.map((step, index) => {
+        const isComplete = index < currentStep;
+        const isCurrent = index === currentStep;
+        const isSkipped = skippedSteps.includes(index);
+
+        return (
+          <div key={step.id} className="flex items-center gap-2">
+            <div className="flex flex-col items-center">
+              <div
+                className={`flex h-8 w-8 items-center justify-center rounded-full text-sm font-medium transition-colors ${
+                  isComplete
+                    ? 'bg-interactive-primary text-white'
+                    : isCurrent
+                      ? 'border-2 border-interactive-primary text-interactive-primary'
+                      : isSkipped
+                        ? 'bg-surface-tertiary text-content-tertiary line-through'
+                        : 'border-2 border-border-primary text-content-tertiary'
+                }`}
+              >
+                {isComplete ? '✓' : index + 1}
+              </div>
+              <span
+                className={`mt-1 text-xs ${
+                  isCurrent ? 'font-medium text-content-primary' : 'text-content-tertiary'
+                }`}
+              >
+                {step.title}
+              </span>
+            </div>
+            {index < ONBOARDING_STEPS.length - 1 && (
+              <div
+                className={`h-0.5 w-8 ${isComplete ? 'bg-interactive-primary' : 'bg-border-primary'}`}
+              />
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+## Step 6: Onboarding Page
+
+```typescript
+// src/app/(protected)/onboarding/page.tsx
+import { redirect } from 'next/navigation';
+import { getOnboardingProgress } from '@/features/onboarding/server';
+import { getSession } from '@/features/auth/server/sessions';
+import { OnboardingFlow } from '@/features/onboarding/components/OnboardingFlow';
+
+export default async function OnboardingPage() {
+  const session = await getSession();
+  if (!session) redirect('/auth/login');
+
+  const progress = await getOnboardingProgress(session.userId);
+  if (progress.isComplete) redirect('/dashboard');
+
+  return (
+    <div className="mx-auto max-w-2xl px-4 py-12">
+      <OnboardingFlow
+        currentStep={progress.currentStep}
+        stepsData={progress.stepsData}
+        skippedSteps={progress.skippedSteps}
+      />
+    </div>
+  );
+}
+```
+
+## Step 7: Onboarding Flow Client Component
+
+```typescript
+// src/features/onboarding/components/OnboardingFlow.tsx
+'use client';
+
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { ONBOARDING_STEPS } from '../config';
+import { OnboardingProgressBar } from './OnboardingProgress';
+
+interface OnboardingFlowProps {
+  currentStep: number;
+  stepsData: Record<string, unknown>;
+  skippedSteps: number[];
+}
+
+export function OnboardingFlow({ currentStep: initialStep, stepsData, skippedSteps: initialSkipped }: OnboardingFlowProps) {
+  const router = useRouter();
+  const [step, setStep] = useState(initialStep);
+  const [skippedSteps, setSkippedSteps] = useState(initialSkipped);
+  const [loading, setLoading] = useState(false);
+
+  const currentStepConfig = ONBOARDING_STEPS[step];
+
+  async function handleComplete(data?: Record<string, unknown>) {
+    setLoading(true);
+    try {
+      const res = await fetch('/api/protected/onboarding/step', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ stepIndex: step, action: 'complete', data }),
+      });
+      const result = await res.json();
+
+      if (result.isComplete) {
+        router.push('/dashboard');
+      } else {
+        setStep(result.nextStep);
+      }
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function handleSkip() {
+    setLoading(true);
+    try {
+      const res = await fetch('/api/protected/onboarding/step', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ stepIndex: step, action: 'skip' }),
+      });
+      const result = await res.json();
+      setSkippedSteps([...skippedSteps, step]);
+
+      if (result.isComplete) {
+        router.push('/dashboard');
+      } else {
+        setStep(result.nextStep);
+      }
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (!currentStepConfig) {
+    router.push('/dashboard');
+    return null;
+  }
+
+  return (
+    <div className="space-y-8">
+      <OnboardingProgressBar currentStep={step} skippedSteps={skippedSteps} />
+
+      <div className="rounded-lg border border-border-primary bg-surface-primary p-6">
+        <h2 className="text-xl font-semibold text-content-primary">{currentStepConfig.title}</h2>
+        <p className="mt-1 text-content-secondary">{currentStepConfig.description}</p>
+
+        <div className="mt-6">
+          {/* Render step-specific content here based on currentStepConfig.id */}
+          {/* Each step should call handleComplete(data) when done */}
+        </div>
+
+        <div className="mt-8 flex items-center justify-between">
+          {!currentStepConfig.required && (
+            <button
+              onClick={handleSkip}
+              disabled={loading}
+              className="text-sm text-content-tertiary hover:text-content-secondary"
+            >
+              Skip this step
+            </button>
+          )}
+          <div className="ml-auto">
+            <button
+              onClick={() => handleComplete()}
+              disabled={loading}
+              className="rounded-md bg-interactive-primary px-6 py-2 text-white hover:bg-interactive-primary-hover disabled:opacity-50"
+            >
+              {step === ONBOARDING_STEPS.length - 1 ? 'Finish' : 'Continue'}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Step 8: Redirect Incomplete Users
+
+In the protected layout, check onboarding status:
+
+```typescript
+// src/app/(protected)/layout.tsx
+import { redirect } from 'next/navigation';
+import { getSession } from '@/features/auth/server/sessions';
+import { isOnboardingComplete } from '@/features/onboarding/server';
+
+export default async function ProtectedLayout({ children }: { children: React.ReactNode }) {
+  const session = await getSession();
+  if (!session) redirect('/auth/login');
+
+  const pathname = /* get current pathname */;
+  const onboardingComplete = await isOnboardingComplete(session.userId);
+
+  if (!onboardingComplete && !pathname.startsWith('/onboarding')) {
+    redirect('/onboarding');
+  }
+
+  return <>{children}</>;
+}
+```
+
+## Testing
+
+1. Create a new user — verify they are redirected to `/onboarding`.
+2. Complete the first step — verify progress updates and next step is shown.
+3. Skip an optional step — verify it is marked as skipped and the flow advances.
+4. Try to skip a required step — verify it is not allowed.
+5. Complete all steps — verify redirect to `/dashboard`.
+6. Return to `/onboarding` after completion — verify redirect to `/dashboard`.
+7. Refresh during onboarding — verify progress is preserved.
+
+## Checklist
+
+- [ ] `OnboardingProgress` model added to Prisma schema
+- [ ] Onboarding steps configured in `src/features/onboarding/config.ts`
+- [ ] Server functions for get, update, skip, and complete
+- [ ] API routes for progress and step actions
+- [ ] Progress indicator component shows current position
+- [ ] Onboarding flow handles step navigation, skip, and complete
+- [ ] Protected layout redirects incomplete users to `/onboarding`
+- [ ] Onboarding page redirects completed users to `/dashboard`
+- [ ] Step-specific data stored as JSON
+- [ ] `db:push` run after schema changes