@olives/devos 2.1.0

package/.agents/skills/nextjs-developer/references/server-components.md

@@ -0,0 +1,384 @@
+# React Server Components
+
+## Server Components (Default)
+
+```tsx
+// app/page.tsx - Server Component by default
+import { db } from '@/lib/db'
+
+export default async function Page() {
+  // Data fetching in Server Component
+  const users = await db.user.findMany()
+
+  return (
+    <div>
+      <h1>Users</h1>
+      <ul>
+        {users.map(user => (
+          <li key={user.id}>{user.name}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+## Benefits of Server Components
+
+- **Zero bundle size** - Server Components don't add JavaScript to client bundle
+- **Direct backend access** - Query databases, read files, use secrets
+- **Automatic code splitting** - Only Client Components add to bundle
+- **Streaming** - Send UI progressively as data loads
+- **No client-side waterfalls** - Fetch all data in parallel on server
+
+## Client Components
+
+```tsx
+// components/counter.tsx
+'use client' // Required directive
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  )
+}
+```
+
+## When to Use Client Components
+
+Use `'use client'` when you need:
+- **Interactivity** - onClick, onChange, event handlers
+- **State** - useState, useReducer
+- **Effects** - useEffect, useLayoutEffect
+- **Browser APIs** - localStorage, window, document
+- **Custom hooks** - Any hook using client-only features
+- **Class components** - Component lifecycle methods
+
+## Composition Pattern
+
+```tsx
+// app/page.tsx - Server Component
+import { ClientWrapper } from './client-wrapper'
+import { db } from '@/lib/db'
+
+export default async function Page() {
+  const data = await db.query()
+
+  return (
+    <div>
+      {/* Server Component content */}
+      <h1>Server Content</h1>
+
+      {/* Pass data to Client Component */}
+      <ClientWrapper initialData={data}>
+        {/* Server Component as children */}
+        <ServerSidebar />
+      </ClientWrapper>
+    </div>
+  )
+}
+
+// components/client-wrapper.tsx
+'use client'
+
+export function ClientWrapper({
+  children,
+  initialData,
+}: {
+  children: React.ReactNode
+  initialData: Data
+}) {
+  const [data, setData] = useState(initialData)
+
+  return (
+    <div>
+      {/* Client Component UI */}
+      <button onClick={() => refresh()}>Refresh</button>
+      {/* Server Component children */}
+      {children}
+    </div>
+  )
+}
+```
+
+## Streaming with Suspense
+
+```tsx
+// app/page.tsx
+import { Suspense } from 'react'
+import { SlowComponent } from './slow-component'
+import { FastComponent } from './fast-component'
+
+export default function Page() {
+  return (
+    <div>
+      {/* Renders immediately */}
+      <FastComponent />
+
+      {/* Shows fallback while loading */}
+      <Suspense fallback={<div>Loading...</div>}>
+        <SlowComponent />
+      </Suspense>
+    </div>
+  )
+}
+
+// components/slow-component.tsx
+async function getData() {
+  await new Promise(resolve => setTimeout(resolve, 3000))
+  return { data: 'Loaded!' }
+}
+
+export async function SlowComponent() {
+  const data = await getData()
+  return <div>{data.data}</div>
+}
+```
+
+## Parallel Data Fetching
+
+```tsx
+// app/dashboard/page.tsx
+async function getUser() {
+  return fetch('https://api.example.com/user')
+}
+
+async function getPosts() {
+  return fetch('https://api.example.com/posts')
+}
+
+export default async function Dashboard() {
+  // Fetch in parallel
+  const [user, posts] = await Promise.all([
+    getUser(),
+    getPosts(),
+  ])
+
+  return (
+    <div>
+      <UserProfile user={user} />
+      <PostsList posts={posts} />
+    </div>
+  )
+}
+```
+
+## Sequential Data Fetching
+
+```tsx
+// app/artist/[id]/page.tsx
+async function getArtist(id: string) {
+  return fetch(`https://api.example.com/artists/${id}`)
+}
+
+async function getAlbums(artistId: string) {
+  return fetch(`https://api.example.com/artists/${artistId}/albums`)
+}
+
+export default async function ArtistPage({ params }: { params: { id: string } }) {
+  // Sequential: albums depends on artist
+  const artist = await getArtist(params.id)
+  const albums = await getAlbums(artist.id)
+
+  return (
+    <div>
+      <h1>{artist.name}</h1>
+      <Albums albums={albums} />
+    </div>
+  )
+}
+```
+
+## Preloading Data
+
+```tsx
+// lib/data.ts
+import { cache } from 'react'
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } })
+})
+
+// components/user-profile.tsx
+export async function UserProfile({ userId }: { userId: string }) {
+  const user = await getUser(userId)
+  return <div>{user.name}</div>
+}
+
+// app/page.tsx
+import { getUser } from '@/lib/data'
+import { UserProfile } from '@/components/user-profile'
+
+export default async function Page() {
+  // Preload
+  getUser('123')
+
+  return (
+    <div>
+      {/* This will use cached result */}
+      <UserProfile userId="123" />
+    </div>
+  )
+}
+```
+
+## Server Component Patterns
+
+### Pattern: Layout with Data Fetching
+
+```tsx
+// app/dashboard/layout.tsx
+import { auth } from '@/lib/auth'
+import { db } from '@/lib/db'
+
+export default async function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const session = await auth()
+  const user = await db.user.findUnique({ where: { id: session.userId } })
+
+  return (
+    <div>
+      <Sidebar user={user} />
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+### Pattern: Conditional Client Components
+
+```tsx
+// app/page.tsx
+import { ClientComponent } from './client-component'
+
+export default async function Page() {
+  const data = await fetchData()
+
+  // Only render Client Component when needed
+  if (data.requiresInteractivity) {
+    return <ClientComponent data={data} />
+  }
+
+  return <div>{data.content}</div>
+}
+```
+
+### Pattern: Server Component with Client Island
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { LikeButton } from './like-button'
+
+export default async function BlogPost({ params }: { params: { slug: string } }) {
+  const post = await getPost(params.slug)
+
+  return (
+    <article>
+      {/* Server-rendered content */}
+      <h1>{post.title}</h1>
+      <div dangerouslySetInnerHTML={{ __html: post.content }} />
+
+      {/* Client island for interactivity */}
+      <LikeButton postId={post.id} initialLikes={post.likes} />
+    </article>
+  )
+}
+```
+
+## Context in Server/Client Components
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { ThemeProvider } from 'next-themes'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>
+}
+
+// app/layout.tsx
+import { Providers } from './providers'
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+## Third-Party Components
+
+```tsx
+// components/carousel-wrapper.tsx
+'use client'
+
+import { Carousel } from 'third-party-carousel'
+
+export function CarouselWrapper({ items }: { items: Item[] }) {
+  return <Carousel items={items} />
+}
+
+// app/page.tsx
+import { CarouselWrapper } from '@/components/carousel-wrapper'
+
+export default async function Page() {
+  const items = await fetchItems()
+  return <CarouselWrapper items={items} />
+}
+```
+
+## Edge Runtime
+
+```tsx
+// app/api/route.ts
+export const runtime = 'edge'
+
+export async function GET() {
+  return new Response('Hello from Edge!')
+}
+
+// app/page.tsx
+export const runtime = 'edge'
+
+export default async function Page() {
+  return <div>Edge-rendered page</div>
+}
+```
+
+## Quick Reference
+
+| Capability | Server Component | Client Component |
+|------------|------------------|------------------|
+| Data fetching | ✅ Yes | ⚠️ Use SWR/React Query |
+| Backend access | ✅ Yes (DB, files) | ❌ No |
+| Event handlers | ❌ No | ✅ Yes |
+| State/Effects | ❌ No | ✅ Yes |
+| Browser APIs | ❌ No | ✅ Yes |
+| Bundle size | 0 KB | Adds to bundle |
+| Streaming | ✅ Yes | ❌ No |
+
+## Best Practices
+
+1. **Default to Server Components** - Only use 'use client' when needed
+2. **Move Client Components down** - Push them to leaves of component tree
+3. **Pass data down** - Fetch in Server Components, pass to Client Components
+4. **Use composition** - Nest Server Components inside Client Components via children
+5. **Cache expensive operations** - Use React cache() for deduplication

package/.agents/skills/nextjs-supabase-auth/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: nextjs-supabase-auth
+description: Expert integration of Supabase Auth with Next.js App Router
+risk: none
+source: vibeship-spawner-skills (Apache 2.0)
+date_added: 2026-02-27
+---
+
+# Next.js + Supabase Auth
+
+Expert integration of Supabase Auth with Next.js App Router
+
+## Capabilities
+
+- nextjs-auth
+- supabase-auth-nextjs
+- auth-middleware
+- auth-callback
+
+## Prerequisites
+
+- Required skills: nextjs-app-router, supabase-backend
+
+## Patterns
+
+### Supabase Client Setup
+
+Create properly configured Supabase clients for different contexts
+
+**When to use**: Setting up auth in a Next.js project
+
+// lib/supabase/client.ts (Browser client)
+'use client'
+import { createBrowserClient } from '@supabase/ssr'
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  )
+}
+
+// lib/supabase/server.ts (Server client)
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+
+export async function createClient() {
+  const cookieStore = await cookies()
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll()
+        },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) => {
+            cookieStore.set(name, value, options)
+          })
+        },
+      },
+    }
+  )
+}
+
+### Auth Middleware
+
+Protect routes and refresh sessions in middleware
+
+**When to use**: You need route protection or session refresh
+
+// middleware.ts
+import { createServerClient } from '@supabase/ssr'
+import { NextResponse, type NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request })
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return request.cookies.getAll()
+        },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) => {
+            response.cookies.set(name, value, options)
+          })
+        },
+      },
+    }
+  )
+
+  // Refresh session if expired
+  const { data: { user } } = await supabase.auth.getUser()
+
+  // Protect dashboard routes
+  if (request.nextUrl.pathname.startsWith('/dashboard') && !user) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+
+  return response
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+}
+
+### Auth Callback Route
+
+Handle OAuth callback and exchange code for session
+
+**When to use**: Using OAuth providers (Google, GitHub, etc.)
+
+// app/auth/callback/route.ts
+import { createClient } from '@/lib/supabase/server'
+import { NextResponse } from 'next/server'
+
+export async function GET(request: Request) {
+  const { searchParams, origin } = new URL(request.url)
+  const code = searchParams.get('code')
+  const next = searchParams.get('next') ?? '/'
+
+  if (code) {
+    const supabase = await createClient()
+    const { error } = await supabase.auth.exchangeCodeForSession(code)
+    if (!error) {
+      return NextResponse.redirect(`${origin}${next}`)
+    }
+  }
+
+  return NextResponse.redirect(`${origin}/auth/error`)
+}
+
+### Server Action Auth
+
+Handle auth operations in Server Actions
+
+**When to use**: Login, logout, or signup from Server Components
+
+// app/actions/auth.ts
+'use server'
+import { createClient } from '@/lib/supabase/server'
+import { redirect } from 'next/navigation'
+import { revalidatePath } from 'next/cache'
+
+export async function signIn(formData: FormData) {
+  const supabase = await createClient()
+  const { error } = await supabase.auth.signInWithPassword({
+    email: formData.get('email') as string,
+    password: formData.get('password') as string,
+  })
+
+  if (error) {
+    return { error: error.message }
+  }
+
+  revalidatePath('/', 'layout')
+  redirect('/dashboard')
+}
+
+export async function signOut() {
+  const supabase = await createClient()
+  await supabase.auth.signOut()
+  revalidatePath('/', 'layout')
+  redirect('/')
+}
+
+### Get User in Server Component
+
+Access the authenticated user in Server Components
+
+**When to use**: Rendering user-specific content server-side
+
+// app/dashboard/page.tsx
+import { createClient } from '@/lib/supabase/server'
+import { redirect } from 'next/navigation'
+
+export default async function DashboardPage() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+
+  if (!user) {
+    redirect('/login')
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {user.email}</h1>
+    </div>
+  )
+}
+
+## Validation Checks
+
+### Using getSession() for Auth Checks
+
+Severity: ERROR
+
+Message: getSession() doesn't verify the JWT. Use getUser() for secure auth checks.
+
+Fix action: Replace getSession() with getUser() for security-critical checks
+
+### OAuth Without Callback Route
+
+Severity: ERROR
+
+Message: Using OAuth but missing callback route at app/auth/callback/route.ts
+
+Fix action: Create app/auth/callback/route.ts to handle OAuth redirects
+
+### Browser Client in Server Context
+
+Severity: ERROR
+
+Message: Browser client used in server context. Use createServerClient instead.
+
+Fix action: Import and use createServerClient from @supabase/ssr
+
+### Protected Routes Without Middleware
+
+Severity: WARNING
+
+Message: No middleware.ts found. Consider adding middleware for route protection.
+
+Fix action: Create middleware.ts to protect routes and refresh sessions
+
+### Hardcoded Auth Redirect URL
+
+Severity: WARNING
+
+Message: Hardcoded localhost redirect. Use origin for environment flexibility.
+
+Fix action: Use window.location.origin or process.env.NEXT_PUBLIC_SITE_URL
+
+### Auth Call Without Error Handling
+
+Severity: WARNING
+
+Message: Auth operation without error handling. Always check for errors.
+
+Fix action: Destructure { data, error } and handle error case
+
+### Auth Action Without Revalidation
+
+Severity: WARNING
+
+Message: Auth action without revalidatePath. Cache may show stale auth state.
+
+Fix action: Add revalidatePath('/', 'layout') after auth operations
+
+### Client-Only Route Protection
+
+Severity: WARNING
+
+Message: Client-side route protection shows flash of content. Use middleware.
+
+Fix action: Move protection to middleware.ts for better UX
+
+## Collaboration
+
+### Delegation Triggers
+
+- database|rls|queries|tables -> supabase-backend (Auth needs database layer)
+- route|page|component|layout -> nextjs-app-router (Auth needs Next.js patterns)
+- deploy|production|vercel -> vercel-deployment (Auth needs deployment config)
+- ui|form|button|design -> frontend (Auth needs UI components)
+
+### Full Auth Stack
+
+Skills: nextjs-supabase-auth, supabase-backend, nextjs-app-router, vercel-deployment
+
+Workflow:
+
+```
+1. Database setup (supabase-backend)
+2. Auth implementation (nextjs-supabase-auth)
+3. Route protection (nextjs-app-router)
+4. Deployment config (vercel-deployment)
+```
+
+### Protected SaaS
+
+Skills: nextjs-supabase-auth, stripe-integration, supabase-backend
+
+Workflow:
+
+```
+1. User authentication (nextjs-supabase-auth)
+2. Customer sync (stripe-integration)
+3. Subscription gating (supabase-backend)
+```
+
+## Related Skills
+
+Works well with: `nextjs-app-router`, `supabase-backend`
+
+## When to Use
+- User mentions or implies: supabase auth next
+- User mentions or implies: authentication next.js
+- User mentions or implies: login supabase
+- User mentions or implies: auth middleware
+- User mentions or implies: protected route
+- User mentions or implies: auth callback
+- User mentions or implies: session management
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.