@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-multi-tenancy/SKILL.md

@@ -0,0 +1,611 @@
+# Skill: Configure Multi-Tenancy
+
+Add teams and organizations to a MARS application, enabling multi-tenant data isolation, role-based org access, and member invitation flows.
+
+## When to Use
+
+Use this skill when the user asks to add organizations, teams, workspaces, multi-tenancy, or team-based access control (e.g., "add teams", "add organizations", "support multiple workspaces").
+
+## Prerequisites
+
+- Auth feature is already working (users can sign up and log in).
+- Read `src/config/app.config.ts` to check current feature flags.
+- Decide on scoping strategy: **org-level** (simpler — all members share one flat namespace) vs. **team-level** (nested teams within an org for department-style isolation). Start with org-level unless the user explicitly needs teams.
+
+## Step 1: Prisma Schema
+
+Create `prisma/schema/organization.prisma`:
+
+```prisma
+model Organization {
+  id        String   @id @default(cuid())
+  name      String
+  slug      String   @unique
+  plan      String   @default("free")
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  memberships Membership[]
+  invitations Invitation[]
+  teams       Team[]
+
+  @@index([slug])
+}
+
+model Team {
+  id    String @id @default(cuid())
+  name  String
+  orgId String
+
+  organization Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
+
+  @@index([orgId])
+}
+
+model Membership {
+  id       String   @id @default(cuid())
+  userId   String
+  orgId    String
+  role     String   @default("member") // owner | admin | member | viewer
+  joinedAt DateTime @default(now())
+
+  user         User         @relation(fields: [userId], references: [id], onDelete: Cascade)
+  organization Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, orgId])
+  @@index([orgId])
+  @@index([userId])
+}
+
+model Invitation {
+  id         String    @id @default(cuid())
+  orgId      String
+  email      String
+  role       String    @default("member")
+  token      String    @unique @default(cuid())
+  expiresAt  DateTime
+  acceptedAt DateTime?
+  createdAt  DateTime  @default(now())
+
+  organization Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
+
+  @@index([orgId])
+  @@index([token])
+  @@index([email])
+}
+```
+
+Add the relation to the User model in `prisma/schema/auth.prisma`:
+
+```prisma
+model User {
+  // ... existing fields
+  memberships Membership[]
+}
+```
+
+Run `yarn db:push` to sync.
+
+## Step 2: Types
+
+Create `src/features/organizations/types.ts`:
+
+```typescript
+export type OrgRole = 'owner' | 'admin' | 'member' | 'viewer';
+
+export const ORG_ROLE_HIERARCHY: Record<OrgRole, number> = {
+  owner: 40,
+  admin: 30,
+  member: 20,
+  viewer: 10,
+};
+
+export interface OrgContext {
+  orgId: string;
+  orgSlug: string;
+  role: OrgRole;
+}
+```
+
+## Step 3: Validation Schemas
+
+Create `src/features/organizations/validation/schemas.ts`:
+
+```typescript
+import { z } from 'zod';
+
+export const organizationSchemas = {
+  create: z.object({
+    name: z.string().min(1, 'Name is required').max(100),
+    slug: z.string().min(2).max(50).regex(/^[a-z0-9-]+$/, 'Slug must be lowercase alphanumeric with hyphens'),
+  }),
+  update: z.object({
+    name: z.string().min(1).max(100).optional(),
+    slug: z.string().min(2).max(50).regex(/^[a-z0-9-]+$/).optional(),
+    plan: z.string().max(50).optional(),
+  }),
+};
+
+export const membershipSchemas = {
+  updateRole: z.object({
+    role: z.enum(['admin', 'member', 'viewer']),
+  }),
+};
+
+export const invitationSchemas = {
+  create: z.object({
+    email: z.string().email('Valid email required'),
+    role: z.enum(['admin', 'member', 'viewer']).default('member'),
+  }),
+};
+
+export type CreateOrganizationInput = z.infer<typeof organizationSchemas.create>;
+export type UpdateOrganizationInput = z.infer<typeof organizationSchemas.update>;
+export type CreateInvitationInput = z.infer<typeof invitationSchemas.create>;
+```
+
+## Step 4: Server Functions
+
+Create `src/features/organizations/server/index.ts`:
+
+```typescript
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import type { CreateOrganizationInput, UpdateOrganizationInput, CreateInvitationInput } from '../validation/schemas';
+import type { OrgRole } from '../types';
+
+// --- Organization CRUD ---
+
+export async function findOrganizationsByUserId(userId: string) {
+  return prisma.organization.findMany({
+    where: { memberships: { some: { userId } } },
+    include: {
+      memberships: { where: { userId }, select: { role: true } },
+      _count: { select: { memberships: true } },
+    },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+
+export async function findOrganizationById(orgId: string) {
+  return prisma.organization.findUnique({
+    where: { id: orgId },
+    include: { _count: { select: { memberships: true, teams: true } } },
+  });
+}
+
+export async function createOrganization(userId: string, data: CreateOrganizationInput) {
+  return prisma.$transaction(async (tx) => {
+    const org = await tx.organization.create({ data });
+    await tx.membership.create({
+      data: { userId, orgId: org.id, role: 'owner' },
+    });
+    return org;
+  });
+}
+
+export async function updateOrganization(orgId: string, data: UpdateOrganizationInput) {
+  return prisma.organization.update({ where: { id: orgId }, data });
+}
+
+export async function deleteOrganization(orgId: string) {
+  return prisma.organization.delete({ where: { id: orgId } });
+}
+
+// --- Membership ---
+
+export async function findMembershipsByOrgId(orgId: string) {
+  return prisma.membership.findMany({
+    where: { orgId },
+    include: { user: { select: { id: true, email: true, name: true } } },
+    orderBy: { joinedAt: 'asc' },
+  });
+}
+
+export async function getUserMembership(userId: string, orgId: string) {
+  return prisma.membership.findUnique({
+    where: { userId_orgId: { userId, orgId } },
+  });
+}
+
+export async function updateMemberRole(membershipId: string, role: OrgRole) {
+  return prisma.membership.update({ where: { id: membershipId }, data: { role } });
+}
+
+export async function removeMember(membershipId: string) {
+  return prisma.membership.delete({ where: { id: membershipId } });
+}
+
+// --- Invitations ---
+
+export async function findInvitationsByOrgId(orgId: string) {
+  return prisma.invitation.findMany({
+    where: { orgId, acceptedAt: null, expiresAt: { gt: new Date() } },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+
+export async function createInvitation(orgId: string, data: CreateInvitationInput) {
+  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
+  return prisma.invitation.create({
+    data: { orgId, email: data.email, role: data.role, expiresAt },
+  });
+}
+
+export async function acceptInvitation(token: string, userId: string) {
+  return prisma.$transaction(async (tx) => {
+    const invitation = await tx.invitation.findUnique({ where: { token } });
+
+    if (!invitation || invitation.acceptedAt || invitation.expiresAt < new Date()) {
+      throw new Error('Invitation is invalid or expired');
+    }
+
+    await tx.membership.create({
+      data: { userId, orgId: invitation.orgId, role: invitation.role as OrgRole },
+    });
+
+    await tx.invitation.update({
+      where: { id: invitation.id },
+      data: { acceptedAt: new Date() },
+    });
+
+    return invitation;
+  });
+}
+
+export async function revokeInvitation(invitationId: string) {
+  return prisma.invitation.delete({ where: { id: invitationId } });
+}
+```
+
+## Step 5: Auth Middleware — `withOrgAccess`
+
+Create `src/features/organizations/server/middleware.ts`:
+
+```typescript
+import 'server-only';
+
+import { NextResponse, type NextRequest } from 'next/server';
+import { verifySessionForAPI } from '@/lib/mars';
+import { getUserMembership } from './index';
+import { ORG_ROLE_HIERARCHY, type OrgRole } from '../types';
+
+interface OrgAuthenticatedRequest extends NextRequest {
+  session: { userId: string; email: string };
+  org: { orgId: string; role: OrgRole };
+}
+
+type OrgRouteParams = { params: Promise<{ orgId: string }> };
+
+/**
+ * Verifies the user has the required role (or higher) in the organization.
+ * Extracts orgId from route params.
+ */
+export function withOrgAccess(
+  requiredRoles: OrgRole[],
+  handler: (request: OrgAuthenticatedRequest, context: OrgRouteParams) => Promise<NextResponse>,
+) {
+  return async (request: NextRequest, context: OrgRouteParams) => {
+    const session = await verifySessionForAPI(request);
+    if (!session) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const { orgId } = await context.params;
+    const membership = await getUserMembership(session.userId, orgId);
+
+    if (!membership) {
+      return NextResponse.json({ error: 'Not a member of this organization' }, { status: 403 });
+    }
+
+    const userLevel = ORG_ROLE_HIERARCHY[membership.role as OrgRole];
+    const requiredLevel = Math.min(...requiredRoles.map((r) => ORG_ROLE_HIERARCHY[r]));
+
+    if (userLevel < requiredLevel) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+    }
+
+    const authedRequest = request as OrgAuthenticatedRequest;
+    authedRequest.session = session;
+    authedRequest.org = { orgId, role: membership.role as OrgRole };
+
+    return handler(authedRequest, context);
+  };
+}
+```
+
+## Step 6: API Routes
+
+### List user's organizations — `src/app/api/protected/organizations/route.ts`
+
+```typescript
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { findOrganizationsByUserId, createOrganization } from '@/features/organizations/server';
+import { organizationSchemas } from '@/features/organizations/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const orgs = await findOrganizationsByUserId(request.session.userId);
+    return NextResponse.json(orgs);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations' });
+  }
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const body = organizationSchemas.create.parse(await request.json());
+    const org = await createOrganization(request.session.userId, body);
+    return NextResponse.json(org, { status: 201 });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations' });
+  }
+});
+```
+
+### Organization details — `src/app/api/protected/organizations/[orgId]/route.ts`
+
+```typescript
+import { handleApiError } from '@/lib/mars';
+import { findOrganizationById, updateOrganization, deleteOrganization } from '@/features/organizations/server';
+import { withOrgAccess } from '@/features/organizations/server/middleware';
+import { organizationSchemas } from '@/features/organizations/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withOrgAccess(['viewer'], async (request, context) => {
+  try {
+    const org = await findOrganizationById(request.org.orgId);
+    if (!org) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    return NextResponse.json(org);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations/[orgId]' });
+  }
+});
+
+export const PATCH = withOrgAccess(['admin'], async (request, context) => {
+  try {
+    const body = organizationSchemas.update.parse(await request.json());
+    const org = await updateOrganization(request.org.orgId, body);
+    return NextResponse.json(org);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations/[orgId]' });
+  }
+});
+
+export const DELETE = withOrgAccess(['owner'], async (request, context) => {
+  try {
+    await deleteOrganization(request.org.orgId);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations/[orgId]' });
+  }
+});
+```
+
+### Members — `src/app/api/protected/organizations/[orgId]/members/route.ts`
+
+```typescript
+import { handleApiError } from '@/lib/mars';
+import { findMembershipsByOrgId, updateMemberRole, removeMember } from '@/features/organizations/server';
+import { withOrgAccess } from '@/features/organizations/server/middleware';
+import { membershipSchemas } from '@/features/organizations/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withOrgAccess(['viewer'], async (request) => {
+  try {
+    const members = await findMembershipsByOrgId(request.org.orgId);
+    return NextResponse.json(members);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations/[orgId]/members' });
+  }
+});
+```
+
+### Invitations — `src/app/api/protected/organizations/[orgId]/invitations/route.ts`
+
+```typescript
+import { handleApiError } from '@/lib/mars';
+import { findInvitationsByOrgId, createInvitation, revokeInvitation } from '@/features/organizations/server';
+import { withOrgAccess } from '@/features/organizations/server/middleware';
+import { invitationSchemas } from '@/features/organizations/validation/schemas';
+import { NextResponse } from 'next/server';
+
+export const GET = withOrgAccess(['admin'], async (request) => {
+  try {
+    const invitations = await findInvitationsByOrgId(request.org.orgId);
+    return NextResponse.json(invitations);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations/[orgId]/invitations' });
+  }
+});
+
+export const POST = withOrgAccess(['admin'], async (request) => {
+  try {
+    const body = invitationSchemas.create.parse(await request.json());
+    const invitation = await createInvitation(request.org.orgId, body);
+    return NextResponse.json(invitation, { status: 201 });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/organizations/[orgId]/invitations' });
+  }
+});
+```
+
+## Step 7: Add Org Context to Session
+
+Extend the JWT payload to include the user's active organization. In `src/features/auth/server/session.ts` (or wherever sessions are built):
+
+```typescript
+interface SessionPayload {
+  userId: string;
+  email: string;
+  role: string;
+  activeOrgId?: string;   // Add this
+  activeOrgRole?: string; // Add this
+}
+```
+
+When the user switches orgs, call a dedicated endpoint to update the session cookie with the new `activeOrgId` and `activeOrgRole`. This keeps the JWT lean while letting middleware make fast decisions.
+
+Alternatively, look up org membership on each request via the `withOrgAccess` middleware (no JWT change needed). This is safer for role changes that need to take effect immediately, but adds a DB query per request.
+
+**Recommendation:** Use `withOrgAccess` middleware for API routes (always fresh from DB) and store `activeOrgId` in the JWT only for UI convenience (org switcher default selection).
+
+## Step 8: Migration Path — Single-User to Multi-Tenant
+
+For existing projects that started as single-user:
+
+1. Run the Prisma migration to add the Organization, Team, Membership, and Invitation models.
+2. Create a backfill script:
+
+```typescript
+// scripts/backfill-orgs.ts
+import { prisma } from '@/lib/prisma';
+
+async function backfill() {
+  const users = await prisma.user.findMany();
+
+  for (const user of users) {
+    const org = await prisma.organization.create({
+      data: {
+        name: `${user.name ?? user.email}'s Organization`,
+        slug: `user-${user.id.slice(0, 8)}`,
+      },
+    });
+
+    await prisma.membership.create({
+      data: { userId: user.id, orgId: org.id, role: 'owner' },
+    });
+  }
+
+  console.log(`Backfilled ${users.length} users into personal organizations.`);
+}
+
+backfill();
+```
+
+3. Add `orgId` to existing data models that need scoping, then backfill with the user's personal org ID.
+4. Update queries to scope by `orgId` instead of (or in addition to) `userId`.
+
+## Step 9: UI Patterns
+
+### Org Switcher Component
+
+```typescript
+// src/features/organizations/components/org-switcher.tsx
+'use client';
+
+import { Select } from '@mars-stack/ui';
+import { useRouter } from 'next/navigation';
+
+interface OrgSwitcherProps {
+  organizations: Array<{ id: string; name: string; slug: string }>;
+  activeOrgId: string;
+}
+
+export function OrgSwitcher({ organizations, activeOrgId }: OrgSwitcherProps) {
+  const router = useRouter();
+
+  async function handleSwitch(orgId: string) {
+    await fetch('/api/protected/organizations/switch', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ orgId }),
+    });
+    router.refresh();
+  }
+
+  return (
+    <Select
+      value={activeOrgId}
+      onValueChange={handleSwitch}
+      options={organizations.map((org) => ({
+        label: org.name,
+        value: org.id,
+      }))}
+    />
+  );
+}
+```
+
+### Invitation Flow
+
+1. Admin creates invitation via `POST /api/protected/organizations/[orgId]/invitations`.
+2. Send invitation email with a link: `{APP_URL}/invite/{token}`.
+3. Invite page calls `POST /api/invitations/accept` with the token and the authenticated user's session.
+4. On success, redirect to the organization dashboard.
+
+## Decision Notes
+
+- **Org-level vs. team-level scoping:** Start with org-level scoping (all data belongs to the org, all members can access). Add teams only when the user needs sub-org isolation (e.g., departments that shouldn't see each other's data). Teams add a second join in every query.
+- **Owner role is non-transferable by default.** Build a dedicated "transfer ownership" flow if needed rather than letting admins promote to owner.
+- **Slug uniqueness** is enforced at the database level. Expose a `/api/protected/organizations/check-slug` endpoint so the UI can validate before submission.
+- **Soft delete vs. hard delete:** The schema above uses hard delete (cascading). For audit trails, add a `deletedAt` column and filter with `where: { deletedAt: null }`.
+
+## Feature Flag
+
+Add to `src/config/app.config.ts`:
+
+```typescript
+features: {
+  // ... existing flags
+  organizations: true,
+}
+```
+
+Gate the org switcher, invitation routes, and org-scoped queries behind this flag.
+
+## Tests
+
+Create `route.test.ts` next to each API route. Mock Prisma and auth:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GET, POST } from './route';
+import { mockAuth } from '@mars-stack/core/test-utils';
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    organization: { findMany: vi.fn(), create: vi.fn() },
+    membership: { create: vi.fn(), findUnique: vi.fn() },
+    $transaction: vi.fn((fn) => fn({
+      organization: { create: vi.fn() },
+      membership: { create: vi.fn() },
+    })),
+  },
+}));
+
+vi.mock('@/lib/mars', () => ({
+  verifySessionForAPI: vi.fn(() => Promise.resolve(mockAuth)),
+  handleApiError: vi.fn((error) => {
+    return new Response(JSON.stringify({ error: 'Internal Server Error' }), { status: 500 });
+  }),
+}));
+```
+
+Test the `withOrgAccess` middleware specifically:
+
+```typescript
+describe('withOrgAccess', () => {
+  it('returns 403 when user is not a member', async () => { /* ... */ });
+  it('returns 403 when user role is below required level', async () => { /* ... */ });
+  it('passes request with org context when authorized', async () => { /* ... */ });
+});
+```
+
+## Checklist
+
+- [ ] Prisma schema created (`organization.prisma`) with Organization, Team, Membership, Invitation models
+- [ ] User model updated with `memberships` relation
+- [ ] `yarn db:push` run to sync schema
+- [ ] Types and validation schemas created
+- [ ] Server functions for org CRUD, membership, and invitations
+- [ ] `withOrgAccess` middleware created
+- [ ] API routes created under `/api/protected/organizations/`
+- [ ] Session/JWT extended with `activeOrgId` (or using middleware-only approach)
+- [ ] Feature flag added to `app.config.ts`
+- [ ] Org switcher component built
+- [ ] Invitation flow (create, email, accept) implemented
+- [ ] Backfill script for existing single-user data (if migrating)
+- [ ] Tests written for API routes and `withOrgAccess` middleware