@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/setup-teams/SKILL.md

@@ -0,0 +1,682 @@
+# Skill: Setup Teams (Meta-Skill)
+
+Orchestrate multi-tenancy with teams/organizations: data models, invitation flow, role hierarchy, org switching, team settings UI, and documentation updates.
+
+## When to Use
+
+Use this skill when the user asks to:
+- Add teams or organizations
+- Set up workspaces or multi-tenancy
+- Add team invitations or member management
+- Build org switching functionality
+
+This meta-skill chains sub-skills in the correct order. For just the multi-tenancy data model, use `configure-multi-tenancy` instead.
+
+## Prerequisites
+
+- Read `src/config/app.config.ts` to check if multi-tenancy features exist
+- Read `prisma/schema/auth.prisma` to understand the current User model
+- Read `src/lib/mars.ts` to check available auth wrappers
+
+## Execution Order
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Phase 0: Plan                                        │
+│   create-execution-plan                              │
+├─────────────────────────────────────────────────────┤
+│ Phase 1: Multi-Tenancy Foundation                    │
+│   configure-multi-tenancy (tenant model, scoping)    │
+├─────────────────────────────────────────────────────┤
+│ Phase 2: Data Layer                                  │
+│   add-prisma-model (Team, Membership, Invitation)   │
+├─────────────────────────────────────────────────────┤
+│ Phase 3: Feature Module                              │
+│   add-feature (teams service, invitation logic)      │
+├─────────────────────────────────────────────────────┤
+│ Phase 4: API Routes                                  │
+│   add-crud-routes (teams, members, invitations)      │
+├─────────────────────────────────────────────────────┤
+│ Phase 5: UI                                          │
+│   add-page (team settings, invite, org switcher)     │
+├─────────────────────────────────────────────────────┤
+│ Phase 6: Auth Integration                            │
+│   Update session, middleware, and context             │
+├─────────────────────────────────────────────────────┤
+│ Phase 7: Testing & Docs                              │
+│   test-api-route → update-architecture-docs          │
+└─────────────────────────────────────────────────────┘
+```
+
+## Phase 0: Create Execution Plan
+
+**Skill:** `create-execution-plan`
+
+Create `docs/exec-plans/active/setup-teams.md` with all tasks listed below.
+
+## Phase 1: Multi-Tenancy Foundation
+
+**Skill:** `configure-multi-tenancy`
+
+1. Enable feature flag:
+
+```typescript
+// src/config/app.config.ts
+features: {
+  teams: true,
+}
+```
+
+2. Decide on tenancy model:
+
+| Model | Description | Use when |
+|-------|-------------|----------|
+| **Team-based** | Users belong to one or more teams | B2B SaaS, collaboration tools |
+| **Org-based** | Hierarchical: Org → Team → User | Enterprise, large organizations |
+| **Workspace-based** | Flat: Users switch between workspaces | Project management, dev tools |
+
+This skill assumes **Team-based** tenancy. Adjust models for org/workspace variants.
+
+## Phase 2: Data Layer
+
+**Skill:** `add-prisma-model`
+
+### Team model
+
+```prisma
+// prisma/schema/teams.prisma
+model Team {
+  id          String   @id @default(cuid())
+  name        String
+  slug        String   @unique
+  avatarUrl   String?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  memberships Membership[]
+  invitations Invitation[]
+
+  @@index([slug])
+}
+
+model Membership {
+  id        String         @id @default(cuid())
+  userId    String
+  teamId    String
+  role      MembershipRole @default(MEMBER)
+  createdAt DateTime       @default(now())
+  updatedAt DateTime       @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+  team Team @relation(fields: [teamId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, teamId])
+  @@index([userId])
+  @@index([teamId])
+  @@index([role])
+}
+
+model Invitation {
+  id        String           @id @default(cuid())
+  email     String
+  teamId    String
+  role      MembershipRole   @default(MEMBER)
+  token     String           @unique @default(cuid())
+  status    InvitationStatus @default(PENDING)
+  invitedBy String
+  expiresAt DateTime
+  createdAt DateTime         @default(now())
+
+  team    Team @relation(fields: [teamId], references: [id], onDelete: Cascade)
+  inviter User @relation("InvitationsSent", fields: [invitedBy], references: [id])
+
+  @@index([email])
+  @@index([teamId])
+  @@index([token])
+  @@index([status])
+}
+
+enum MembershipRole {
+  OWNER
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+enum InvitationStatus {
+  PENDING
+  ACCEPTED
+  EXPIRED
+  REVOKED
+}
+```
+
+### Update User model
+
+```prisma
+// In prisma/schema/auth.prisma
+model User {
+  // ... existing fields
+  memberships     Membership[]
+  invitationsSent Invitation[] @relation("InvitationsSent")
+  activeTeamId    String?
+}
+```
+
+Run `yarn db:push`.
+
+## Phase 3: Feature Module
+
+**Skill:** `add-feature`
+
+Create `src/features/teams/`:
+
+```
+src/features/teams/
+├── components/
+│   ├── TeamSwitcher.tsx       # Org/team switcher dropdown
+│   ├── MemberList.tsx         # Team member list with roles
+│   ├── InviteForm.tsx         # Invite new member form
+│   ├── InvitationList.tsx     # Pending invitations
+│   ├── TeamSettingsForm.tsx   # Edit team name, avatar
+│   └── index.ts
+├── server/
+│   ├── index.ts               # Team queries and mutations
+│   ├── invitations.ts         # Invitation logic
+│   └── membership.ts          # Membership management
+├── hooks/
+│   ├── useActiveTeam.ts       # Current team context hook
+│   └── index.ts
+├── validation/
+│   └── schemas.ts             # Zod schemas
+└── types.ts                   # Team-related types
+```
+
+### Server module: Teams
+
+```typescript
+// src/features/teams/server/index.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+
+export async function getUserTeams(userId: string) {
+  return prisma.membership.findMany({
+    where: { userId },
+    include: { team: true },
+    orderBy: { createdAt: 'asc' },
+  });
+}
+
+export async function getTeamById(teamId: string, userId: string) {
+  return prisma.team.findFirst({
+    where: {
+      id: teamId,
+      memberships: { some: { userId } },
+    },
+    include: {
+      memberships: {
+        include: { user: { select: { id: true, email: true, name: true } } },
+        orderBy: { createdAt: 'asc' },
+      },
+    },
+  });
+}
+
+export async function createTeam(userId: string, name: string) {
+  const slug = generateSlug(name);
+
+  return prisma.$transaction(async (tx) => {
+    const team = await tx.team.create({
+      data: { name, slug },
+    });
+
+    await tx.membership.create({
+      data: { userId, teamId: team.id, role: 'OWNER' },
+    });
+
+    await tx.user.update({
+      where: { id: userId },
+      data: { activeTeamId: team.id },
+    });
+
+    return team;
+  });
+}
+
+function generateSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    + '-' + Math.random().toString(36).slice(2, 6);
+}
+```
+
+### Server module: Invitations
+
+```typescript
+// src/features/teams/server/invitations.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import { apiLogger } from '@/lib/mars';
+import type { MembershipRole } from '@db';
+
+export async function createInvitation(
+  teamId: string,
+  email: string,
+  role: MembershipRole,
+  invitedBy: string,
+) {
+  const existingMember = await prisma.membership.findFirst({
+    where: {
+      teamId,
+      user: { email },
+    },
+  });
+
+  if (existingMember) {
+    throw new Error('User is already a member of this team');
+  }
+
+  const existingInvite = await prisma.invitation.findFirst({
+    where: { teamId, email, status: 'PENDING' },
+  });
+
+  if (existingInvite) {
+    throw new Error('An invitation is already pending for this email');
+  }
+
+  const expiresAt = new Date();
+  expiresAt.setDate(expiresAt.getDate() + 7);
+
+  const invitation = await prisma.invitation.create({
+    data: { teamId, email, role, invitedBy, expiresAt },
+    include: { team: true },
+  });
+
+  apiLogger.info({ teamId, email, role }, 'Team invitation created');
+
+  return invitation;
+}
+
+export async function acceptInvitation(token: string, userId: string) {
+  const invitation = await prisma.invitation.findUnique({
+    where: { token },
+  });
+
+  if (!invitation) throw new Error('Invitation not found');
+  if (invitation.status !== 'PENDING') throw new Error('Invitation is no longer valid');
+  if (invitation.expiresAt < new Date()) {
+    await prisma.invitation.update({
+      where: { id: invitation.id },
+      data: { status: 'EXPIRED' },
+    });
+    throw new Error('Invitation has expired');
+  }
+
+  return prisma.$transaction(async (tx) => {
+    await tx.invitation.update({
+      where: { id: invitation.id },
+      data: { status: 'ACCEPTED' },
+    });
+
+    const membership = await tx.membership.create({
+      data: {
+        userId,
+        teamId: invitation.teamId,
+        role: invitation.role,
+      },
+    });
+
+    return membership;
+  });
+}
+
+export async function revokeInvitation(invitationId: string, teamId: string) {
+  return prisma.invitation.update({
+    where: { id: invitationId, teamId },
+    data: { status: 'REVOKED' },
+  });
+}
+```
+
+### Role hierarchy
+
+```typescript
+// src/features/teams/server/membership.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import type { MembershipRole } from '@db';
+
+const ROLE_HIERARCHY: Record<MembershipRole, number> = {
+  OWNER: 4,
+  ADMIN: 3,
+  MEMBER: 2,
+  VIEWER: 1,
+};
+
+export function canManageRole(actorRole: MembershipRole, targetRole: MembershipRole): boolean {
+  return ROLE_HIERARCHY[actorRole] > ROLE_HIERARCHY[targetRole];
+}
+
+export async function updateMemberRole(
+  teamId: string,
+  targetUserId: string,
+  newRole: MembershipRole,
+  actorUserId: string,
+) {
+  const actorMembership = await prisma.membership.findUnique({
+    where: { userId_teamId: { userId: actorUserId, teamId } },
+  });
+
+  if (!actorMembership || !canManageRole(actorMembership.role, newRole)) {
+    throw new Error('Insufficient permissions to assign this role');
+  }
+
+  return prisma.membership.update({
+    where: { userId_teamId: { userId: targetUserId, teamId } },
+    data: { role: newRole },
+  });
+}
+
+export async function removeMember(
+  teamId: string,
+  targetUserId: string,
+  actorUserId: string,
+) {
+  if (targetUserId === actorUserId) {
+    throw new Error('Cannot remove yourself. Transfer ownership first.');
+  }
+
+  const actorMembership = await prisma.membership.findUnique({
+    where: { userId_teamId: { userId: actorUserId, teamId } },
+  });
+
+  const targetMembership = await prisma.membership.findUnique({
+    where: { userId_teamId: { userId: targetUserId, teamId } },
+  });
+
+  if (!actorMembership || !targetMembership) {
+    throw new Error('Membership not found');
+  }
+
+  if (!canManageRole(actorMembership.role, targetMembership.role)) {
+    throw new Error('Insufficient permissions');
+  }
+
+  return prisma.membership.delete({
+    where: { userId_teamId: { userId: targetUserId, teamId } },
+  });
+}
+```
+
+## Phase 4: API Routes
+
+**Skill:** `add-crud-routes`
+
+### Team routes
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `/api/protected/teams` | GET | `withAuthNoParams` | List user's teams |
+| `/api/protected/teams` | POST | `withAuthNoParams` | Create new team |
+| `/api/protected/teams/[teamId]` | GET | `withAuth` | Get team details |
+| `/api/protected/teams/[teamId]` | PUT | `withAuth` | Update team settings |
+| `/api/protected/teams/[teamId]` | DELETE | `withAuth` | Delete team (owner only) |
+
+### Member routes
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `/api/protected/teams/[teamId]/members` | GET | `withAuth` | List team members |
+| `/api/protected/teams/[teamId]/members/[userId]` | PUT | `withAuth` | Update member role |
+| `/api/protected/teams/[teamId]/members/[userId]` | DELETE | `withAuth` | Remove member |
+
+### Invitation routes
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `/api/protected/teams/[teamId]/invitations` | GET | `withAuth` | List pending invitations |
+| `/api/protected/teams/[teamId]/invitations` | POST | `withAuth` | Send invitation |
+| `/api/protected/teams/[teamId]/invitations/[id]` | DELETE | `withAuth` | Revoke invitation |
+| `/api/protected/invitations/accept` | POST | `withAuthNoParams` | Accept invitation by token |
+
+### Active team route
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `/api/protected/user/active-team` | PUT | `withAuthNoParams` | Switch active team |
+
+**All team-scoped routes must verify membership:**
+
+```typescript
+export const GET = withAuth(async (request, { params }) => {
+  const { teamId } = await params;
+  const team = await getTeamById(teamId, request.session.userId);
+  if (!team) {
+    return NextResponse.json({ error: 'Team not found' }, { status: 404 });
+  }
+  // ...
+});
+```
+
+**Role-gated operations (admin+ for invitations, owner for delete):**
+
+```typescript
+const membership = team.memberships.find(m => m.userId === request.session.userId);
+if (!membership || ROLE_HIERARCHY[membership.role] < ROLE_HIERARCHY.ADMIN) {
+  return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 });
+}
+```
+
+## Phase 5: UI
+
+**Skill:** `add-page`
+
+### Team settings page
+
+Create `src/app/(protected)/settings/team/page.tsx`:
+- Team name and slug editor
+- Avatar upload (if storage configured)
+- Member list with role badges
+- Invite member form
+- Pending invitations list
+- Danger zone: delete team (owner only)
+
+### Team switcher component
+
+```tsx
+// src/features/teams/components/TeamSwitcher.tsx
+'use client';
+
+import { useActiveTeam } from '@/features/teams/hooks/useActiveTeam';
+import { Select } from '@mars-stack/ui';
+
+export function TeamSwitcher() {
+  const { teams, activeTeam, switchTeam, loading } = useActiveTeam();
+
+  if (loading || teams.length <= 1) return null;
+
+  return (
+    <Select
+      value={activeTeam?.id}
+      onChange={(teamId) => switchTeam(teamId)}
+      options={teams.map(t => ({ value: t.team.id, label: t.team.name }))}
+    />
+  );
+}
+```
+
+### Active team hook
+
+```tsx
+// src/features/teams/hooks/useActiveTeam.ts
+'use client';
+
+import { useEffect, useState, useCallback } from 'react';
+
+interface TeamMembership {
+  id: string;
+  role: string;
+  team: { id: string; name: string; slug: string };
+}
+
+export function useActiveTeam() {
+  const [teams, setTeams] = useState<TeamMembership[]>([]);
+  const [activeTeam, setActiveTeam] = useState<TeamMembership | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/protected/teams')
+      .then(res => res.json())
+      .then((data: TeamMembership[]) => {
+        setTeams(data);
+        const active = data.find(t => t.team.id === localStorage.getItem('activeTeamId'));
+        setActiveTeam(active ?? data[0] ?? null);
+      })
+      .finally(() => setLoading(false));
+  }, []);
+
+  const switchTeam = useCallback(async (teamId: string) => {
+    await fetch('/api/protected/user/active-team', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ teamId }),
+    });
+    localStorage.setItem('activeTeamId', teamId);
+    const team = teams.find(t => t.team.id === teamId);
+    if (team) setActiveTeam(team);
+  }, [teams]);
+
+  return { teams, activeTeam, switchTeam, loading };
+}
+```
+
+### Invitation acceptance page
+
+Create `src/app/(protected)/invitations/accept/page.tsx`:
+- Reads `?token=` from search params
+- Calls accept invitation API
+- Redirects to the team on success
+
+### Invitation email
+
+If email is configured, send invitation emails using the `configure-email` skill pattern:
+
+```typescript
+await sendEmail({
+  to: email,
+  subject: `You've been invited to join ${team.name}`,
+  html: invitationEmailTemplate({ team, inviterName, acceptUrl }),
+});
+```
+
+## Phase 6: Auth Integration
+
+### Extend session with team context
+
+Add `activeTeamId` to the JWT session claims so team-scoped queries can use it:
+
+```typescript
+// When creating/refreshing session, include activeTeamId
+const sessionData = {
+  userId: user.id,
+  email: user.email,
+  role: user.role,
+  activeTeamId: user.activeTeamId,
+};
+```
+
+### Team-scoped queries
+
+For features that are team-scoped, queries should filter by `teamId`:
+
+```typescript
+export async function findProjectsByTeam(teamId: string) {
+  return prisma.project.findMany({
+    where: { teamId },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+```
+
+### Middleware consideration
+
+If certain routes should only be accessible to team members, add team verification in the route handler (not middleware, to keep middleware thin).
+
+## Phase 7: Testing & Documentation
+
+**Skill:** `test-api-route` + `update-architecture-docs`
+
+### Tests
+
+1. Unit test team CRUD routes
+2. Unit test invitation flow (create, accept, revoke, expiry)
+3. Unit test role hierarchy (canManageRole, permission checks)
+4. Unit test membership management (add, remove, update role)
+5. E2E test: create team → invite member → accept → verify access
+
+### Documentation updates
+
+1. Update `docs/QUALITY_SCORE.md`:
+
+```markdown
+| Teams | B | Team CRUD, invitations, role hierarchy, org switching |
+```
+
+2. Update `AGENTS.md`:
+   - Add teams feature to directory listing
+   - Document team-scoped query pattern
+
+3. Mark execution plan as complete
+
+## Data Scoping Decision
+
+**When to scope data by team vs. by user:**
+
+| Scope by Team | Scope by User |
+|---------------|---------------|
+| Projects, documents, shared resources | Personal settings, profile |
+| Billing and subscriptions | Notification preferences |
+| API keys and integrations | Security settings |
+| Audit logs (team actions) | Auth sessions |
+
+For team-scoped models, add `teamId` field and index:
+
+```prisma
+model Project {
+  // ...
+  teamId String
+  team   Team @relation(fields: [teamId], references: [id], onDelete: Cascade)
+
+  @@index([teamId])
+}
+```
+
+## Checklist
+
+- [ ] Execution plan created
+- [ ] Multi-tenancy feature flag enabled
+- [ ] Team, Membership, Invitation models in Prisma
+- [ ] Membership role enum (OWNER, ADMIN, MEMBER, VIEWER)
+- [ ] Invitation status enum (PENDING, ACCEPTED, EXPIRED, REVOKED)
+- [ ] User model extended with `activeTeamId`
+- [ ] Team CRUD server module
+- [ ] Invitation server module (create, accept, revoke)
+- [ ] Role hierarchy with permission checks
+- [ ] Team CRUD API routes
+- [ ] Member management API routes
+- [ ] Invitation API routes
+- [ ] Active team switching API route
+- [ ] Team settings page with member management
+- [ ] Team switcher component
+- [ ] Invitation acceptance flow
+- [ ] Session extended with activeTeamId
+- [ ] Invitation emails (if email configured)
+- [ ] Unit tests for all API routes
+- [ ] E2E test for invitation flow
+- [ ] QUALITY_SCORE.md updated
+- [ ] Execution plan completed