@luanpdd/kit-mcp 1.7.0 → 1.8.1

package/kit/skills/_shared-supabase/glossary.md

@@ -0,0 +1,180 @@
+# Glossário Supabase — Termos, Comandos e Patterns Canônicos
+
+> Arquivo de referência compartilhado pelas skills `supabase-*`. **NÃO é skill** — não tem `description:` triggerável; não aparece em `listKit`. Cross-referenciado pelas 11 skills via Markdown link relativo.
+
+---
+
+## (a) Termos PT-BR ↔ EN
+
+### Authorization e Auth
+
+| EN | PT-BR / Significado |
+|---|---|
+| **RLS** | Row Level Security — segurança em nível de linha. Filtra automaticamente quais linhas de uma tabela cada usuário vê/modifica baseado em policies. |
+| **policy** | Política de RLS — regra `create policy ... on <table> for <op> ...`. Sempre granular por operação (SELECT/INSERT/UPDATE/DELETE). |
+| **`auth.uid()`** | Função que retorna o UUID do usuário autenticado da sessão atual. **Sempre** usar em `(select auth.uid())` em policies. |
+| **`auth.jwt()`** | Função que retorna o JWT decodificado da sessão. Acesso via `auth.jwt()->'app_metadata'` ou `auth.jwt()->>'aal'`. |
+| **`app_metadata`** | Metadata controlado pelo backend (apenas service_role pode mutar). **Use para roles/permissions** em RLS. |
+| **`user_metadata`** | Metadata controlado pelo cliente (`auth.updateUser({data: ...})`). **NUNCA** use em policy de autorização — privilege escalation. |
+| **service_role** | Role do Postgres com bypass total de RLS. **NUNCA** expor ao cliente — vazamento = acesso total ao DB. |
+| **anon** | Role para requests sem autenticação. RLS aplicado normalmente. |
+| **authenticated** | Role para usuário autenticado. RLS aplicado normalmente. |
+| **public** | Role default — equivale a anon + authenticated juntos. Evite — sempre use `to authenticated` ou `to anon` explícito. |
+| **AAL** | Authentication Assurance Level. `aal1` = senha apenas; `aal2` = senha + 2FA. Verifica via `(auth.jwt()->>'aal')::text`. |
+
+### Database e Schema
+
+| EN | PT-BR / Significado |
+|---|---|
+| **`schemas/`** | Pasta `supabase/schemas/` — fonte da verdade declarative do schema. Editar aqui, depois `db diff` gera migration. |
+| **`migrations/`** | Pasta `supabase/migrations/` — arquivos `YYYYMMDDHHmmss_<name>.sql` versionados em git. |
+| **`db diff`** | `supabase db diff -f <name>` — gera migration a partir do diff entre schemas/ declarado e DB local atual. |
+| **`db reset`** | `supabase db reset` — recria DB local do zero + reaplica todas as migrations + seeds. |
+| **`search_path`** | Caminho de busca de schema do Postgres. **Sempre** `set search_path = ''` em funções. |
+| **schema-qualified** | Referência a objeto com schema explícito: `public.tasks` em vez de só `tasks`. Obrigatório quando `search_path = ''`. |
+| **`SECURITY INVOKER`** | Função executa com permissões de quem chamou. Default obrigatório. |
+| **`SECURITY DEFINER`** | Função executa com permissões do owner. Apenas com justificativa documentada. |
+| **`IMMUTABLE`** | Função sempre retorna o mesmo para os mesmos inputs (sem consultar DB). |
+| **`STABLE`** | Função consulta DB mas não modifica — mesmo resultado dentro de uma transação. |
+| **`VOLATILE`** | Default. Função pode retornar valores diferentes ou ter side effects. |
+
+### Realtime
+
+| EN | PT-BR / Significado |
+|---|---|
+| **broadcast** | Mensagens custom via WebSocket — tipo recomendado em 2026 (substitui `postgres_changes` em apps novos). |
+| **postgres_changes** | Pattern legado de receber mudanças do DB via stream. Single-threaded — não escala. **Migrar para broadcast.** |
+| **presence** | Tracking de "quem está online". Usar **com moderação** — só para presence real (online status, cursor de colaboração). |
+| **channel** | Canal de comunicação — naming canônico `scope:entity:id` (ex: `room:123:messages`). |
+| **private channel** | Canal autenticado — `private: true` + RLS sobre `realtime.messages`. **Default em produção.** |
+| **`realtime.broadcast_changes`** | Função SQL para emitir broadcast de dentro do Postgres (de trigger). |
+| **`realtime.send`** | Função SQL para emitir mensagem custom (não amarrada a tabela). |
+
+### Edge Functions
+
+| EN | PT-BR / Significado |
+|---|---|
+| **Edge Function** | Função serverless Deno hospedada por Supabase. Roda perto do usuário. |
+| **`Deno.serve`** | Built-in para HTTP server em Edge Functions (NÃO usar `serve` de `deno.land/std`). |
+| **`EdgeRuntime.waitUntil`** | Permite tarefa background continuar após response retornar. |
+| **`npm:` / `jsr:`** | Specifiers de import obrigatórios (sem bare specifiers). Ex: `import x from "npm:hono@4.6.7"`. |
+
+### Storage e Vector
+
+| EN | PT-BR / Significado |
+|---|---|
+| **bucket** | Container de arquivos — público ou privado. Privado por default. |
+| **signed URL** | URL temporária com expiration para download de arquivo privado. |
+| **`storage.objects`** | Tabela onde Storage grava metadados — RLS aplicado aqui controla acesso. |
+| **multi-tenant path isolation** | Pattern: prefixar path do arquivo com `auth.uid()` (`{user_id}/file.png`) para isolar por tenant via RLS. |
+| **TUS** | Tus Resumable Upload protocol — upload em chunks resumable. |
+| **pgvector** | Extensão Postgres para embeddings/similarity search. |
+| **HNSW** | Hierarchical Navigable Small World — index para vector. **Recall melhor.** Default em 2026. |
+| **IVFFlat** | Inverted File Flat — index alternativo. Mais rápido com volumes grandes mas recall menor. |
+| **`<=>`** | Operador cosine distance em pgvector. |
+| **`<#>`** | Operador inner product em pgvector. |
+| **`<->`** | Operador L2 (euclidean) distance em pgvector. |
+
+### Background Jobs
+
+| EN | PT-BR / Significado |
+|---|---|
+| **`pg_cron`** | Extensão para jobs cron dentro do Postgres. Schedule SQL/funções. |
+| **`pgmq`** | Postgres Message Queue — extensão de queues. Requer Postgres 15.6.1.143+. |
+| **`pg_net`** | Extensão para requests HTTP de dentro do Postgres. v0.10.0+. |
+
+### Branching
+
+| EN | PT-BR / Significado |
+|---|---|
+| **branch database** | Cópia preview do DB de produção para feature branches. |
+| **persistent branch** | Branch que sobrevive entre PRs (staging long-lived). |
+| **preview branch** | Branch criado para PR específico — destruído ao merge. |
+
+---
+
+## (b) Comandos CLI canônicos
+
+```bash
+# Schema declarative
+supabase stop                                          # parar containers (necessário antes de db diff)
+supabase db diff -f <name>                             # gera migration de schemas/ → migrations/
+supabase db reset                                      # reset local + reaplica migrations + seeds
+supabase db push                                       # aplica migrations não aplicadas no DB remote
+supabase db pull                                       # pulla mudanças remote → cria migration local
+
+# Migrations
+supabase migration new <name>                          # cria migration vazia com timestamp UTC
+
+# Edge Functions
+supabase functions new <name>                          # cria boilerplate de Edge Function
+supabase functions deploy <name>                       # deploy para Supabase
+supabase functions invoke <name> --body '{}'           # invoca localmente
+
+# Tipos
+supabase gen types typescript --local > types/db.ts    # gera tipos do schema local
+supabase gen types typescript --linked > types/db.ts   # gera tipos do remote linked
+
+# Project lifecycle
+supabase init                                          # inicializa supabase/ no projeto
+supabase start                                         # sobe stack local (Postgres + Studio + Auth + ...)
+supabase stop                                          # derruba stack local
+supabase status                                        # status dos containers locais
+supabase link --project-ref <ref>                      # linka projeto local com remote
+
+# Branching
+supabase branches create <name>                        # cria preview branch
+supabase branches list                                 # lista branches
+supabase branches delete <name>                        # deleta branch (importante para custo!)
+
+# Secrets
+supabase secrets set --env-file .env.production        # setar secrets em remote
+supabase secrets list                                  # listar (sem revelar valores)
+```
+
+---
+
+## (c) Patterns canônicos consolidados
+
+### Pattern: `(select auth.uid())` wrapper em RLS
+- Sem `(select)`: degradação até **1000×** em queries com filtro RLS
+- Detalhes: [supabase-rls-policies](../supabase-rls-policies/SKILL.md)
+
+### Pattern: `set search_path = ''` em funções
+- Sem isso: vulnerável a hijack de schema via `search_path` manipulation
+- Detalhes: [supabase-database-functions](../supabase-database-functions/SKILL.md)
+
+### Pattern: `getAll`/`setAll` cookies em SSR (Next.js)
+- Pacote `@supabase/ssr` — **NUNCA** `@supabase/auth-helpers-nextjs` (deprecated)
+- Detalhes: [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md)
+
+### Pattern: `cron → pgmq → Edge Function` (background jobs)
+- Schedule via `pg_cron` → enqueue em `pgmq` → consumir e disparar `pg_net.http_post()` para Edge Function
+- Sem dep externa (Inngest/Trigger.dev) — tudo dentro de Supabase
+- Detalhes: [supabase-cron-queues](../supabase-cron-queues/SKILL.md)
+
+### Pattern: RAG with permissions (similarity + RLS)
+- Embeddings em coluna vector + RLS policy filtrando por `user_id` ou `org_id`
+- Sem RLS, qualquer cliente vê embeddings de todos os tenants
+- Detalhes: [supabase-pgvector-rag](../supabase-pgvector-rag/SKILL.md)
+
+### Pattern: multi-tenant path isolation em Storage
+- Path do arquivo prefixado com `auth.uid()` ou `org_id`: `{user_id}/avatar.png`, `{org_id}/docs/file.pdf`
+- RLS sobre `storage.objects` valida que o cliente acessa apenas o próprio prefixo
+- Detalhes: [supabase-storage](../supabase-storage/SKILL.md)
+
+### Pattern: declarative-first → diff → migration
+- Editar schemas em `supabase/schemas/*.sql`
+- Rodar `supabase stop && supabase db diff -f <name>` para gerar migration em `supabase/migrations/`
+- Revisar migration manualmente antes de aplicar
+- Detalhes: [supabase-declarative-schema](../supabase-declarative-schema/SKILL.md)
+
+### Pattern: `private: true` em Realtime channels
+- Default em produção (2026) — desabilita acesso anônimo
+- Requer RLS sobre `realtime.messages` para SELECT (read) e INSERT (write)
+- Detalhes: [supabase-realtime](../supabase-realtime/SKILL.md)
+
+### Pattern: schema-qualified em Edge Functions chamando Supabase
+- Function consulta `public.tasks` (não `tasks`) quando usar service-role client
+- Combina com `set search_path = ''` em DB functions chamadas via RPC
+- Detalhes: [supabase-edge-functions](../supabase-edge-functions/SKILL.md)

package/kit/skills/supabase-auth-ssr/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: supabase-auth-ssr
+description: Use ao bootstrap Next.js v16 + Supabase Auth — @supabase/ssr, getAll/setAll APENAS, NUNCA auth-helpers-nextjs, proxy completo com getUser e redirects.
+---
+
+# Supabase — Auth SSR (Next.js v16+)
+
+## Quando usar
+
+LLM carrega esta skill quando bootstrap ou auditar autenticação Supabase em Next.js v16+ (App Router) com SSR. Trigger phrases:
+
+- "Next.js + Supabase auth"
+- "@supabase/ssr"
+- "createServerClient", "createBrowserClient"
+- "middleware.ts auth", "proxy auth"
+- "cookies getAll setAll"
+- "Supabase auth Next.js v16"
+
+## Regras absolutas
+
+**WARNING — NEVER use auth-helpers-nextjs.** O pacote `@supabase/auth-helpers-nextjs` está **DEPRECATED** e **quebra em Next.js v16+** (cookies API mudou). **SEMPRE** use `@supabase/ssr`.
+
+**Outras regras:**
+
+- **Padrão exclusivo `getAll`/`setAll`** para cookies — **NUNCA** `get`/`set`/`remove` individuais. Os métodos individuais não funcionam corretamente com middleware/Server Actions em Next.js v16+.
+- **Browser client e Server client são distintos:**
+  - Browser (`createBrowserClient`) → para Client Components ("use client")
+  - Server (`createServerClient`) → para Server Components, Route Handlers, Server Actions
+- **Middleware (`middleware.ts`) obrigatório** para refresh de sessão SSR. Deve chamar `supabase.auth.getUser()` em cada request.
+- **Auth method order** — após `createServerClient` mas **ANTES** de `getUser()`, NÃO chamar nada que produza response intermediário. Os cookies precisam fluir corretamente.
+- **`NEXT_PUBLIC_*` apenas para anon key** (`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`). **NUNCA** `NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY` — service_role bypassa RLS e seria exposto ao cliente (anti-pitfall B6).
+- **Single serverClient factory** — não criar múltiplos clients em layouts (race condition na refresh de token — B13).
+
+## Patterns canônicos
+
+### Browser client — Client Components
+
+```ts
+// utils/supabase/client.ts — PT-BR: client para Client Components
+import { createBrowserClient } from '@supabase/ssr'
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  )
+}
+```
+
+```tsx
+// PT-BR: uso em Client Component
+'use client'
+import { createClient } from '@/utils/supabase/client'
+
+export function LogoutButton() {
+  const supabase = createClient()
+  return <button onClick={() => supabase.auth.signOut()}>Sair</button>
+}
+```
+
+### Server client — Server Components / Server Actions
+
+```ts
+// utils/supabase/server.ts — PT-BR: client para Server Components/Actions/Route Handlers
+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) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            )
+          } catch {
+            // PT-BR: ok ignorar — chamado em Server Component (sem permissão de set)
+            // se proxy faz refresh, sessão fica saudável mesmo sem set aqui
+          }
+        },
+      },
+    }
+  )
+}
+```
+
+```tsx
+// PT-BR: uso em Server Component
+import { createClient } from '@/utils/supabase/server'
+
+export default async function Dashboard() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) return <p>Não autenticado</p>
+  return <p>Olá, {user.email}</p>
+}
+```
+
+### Middleware — refresh de sessão (obrigatório)
+
+```ts
+// middleware.ts — PT-BR: proxy obrigatório para refresh de sessão SSR
+import { createServerClient } from '@supabase/ssr'
+import { NextResponse, type NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  let supabaseResponse = 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 }) =>
+            request.cookies.set(name, value)
+          )
+          supabaseResponse = NextResponse.next({ request })
+          cookiesToSet.forEach(({ name, value, options }) =>
+            supabaseResponse.cookies.set(name, value, options)
+          )
+        },
+      },
+    }
+  )
+
+  // PT-BR: ATENÇÃO — não execute código entre createServerClient e getUser()
+  // (qualquer cookie set/get fora desse path quebra refresh silencioso)
+  const { data: { user } } = await supabase.auth.getUser()
+
+  // PT-BR: redirect para /login se sem user
+  if (!user && !request.nextUrl.pathname.startsWith('/login')) {
+    const url = request.nextUrl.clone()
+    url.pathname = '/login'
+    return NextResponse.redirect(url)
+  }
+
+  // PT-BR: IMPORTANTE — sempre retornar supabaseResponse (cookies precisam fluir)
+  return supabaseResponse
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+}
+```
+
+### Login com email/senha (Server Action)
+
+```ts
+// app/login/actions.ts
+'use server'
+import { createClient } from '@/utils/supabase/server'
+import { redirect } from 'next/navigation'
+
+export async function loginAction(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 }
+  redirect('/dashboard')
+}
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Importar de `@supabase/auth-helpers-nextjs`
+
+**Errado:**
+```ts
+import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs'
+import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'
+```
+
+**Por quê:** `@supabase/auth-helpers-nextjs` está **DEPRECATED**. Quebra em Next.js v16+ (cookies API mudou). Não recebe mais updates de segurança.
+
+**Certo:**
+```ts
+import { createServerClient, createBrowserClient } from '@supabase/ssr'
+```
+
+### Anti-pattern 2: `cookies: { get, set, remove }` (individual)
+
+**Errado:**
+```ts
+{
+  cookies: {
+    get(name: string) { return cookieStore.get(name) },
+    set(name: string, value: string) { cookieStore.set(name, value) },
+    remove(name: string) { cookieStore.remove(name) },
+  }
+}
+```
+
+**Por quê:** cookie methods individuais quebram em middleware quando há múltiplos cookies sendo set/get em uma única request. `getAll`/`setAll` são chamados em batch e preservam ordem.
+
+**Certo:** ver pattern "Server client" e "Middleware" acima.
+
+### Anti-pattern 3: `NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY`
+
+**Errado:**
+```bash
+# .env.local
+NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY=eyJhbG...
+```
+
+**Por quê:** `NEXT_PUBLIC_*` é **público** no client bundle. `service_role` bypassa RLS — vazamento = banco totalmente exposto.
+
+**Certo:**
+```bash
+# .env.local
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...   # ok público
+SUPABASE_SERVICE_ROLE_KEY=eyJhbG...         # privado — sem NEXT_PUBLIC_
+```
+
+Use `service_role` apenas em código server-side que NUNCA é embarcado no bundle client (Route Handlers, Server Actions com `'use server'`, Edge Functions).
+
+### Anti-pattern 4: Múltiplos serverClient em layouts (race condition)
+
+**Errado:**
+```tsx
+// app/layout.tsx
+const supabase1 = await createClient()
+const { user } = await supabase1.auth.getUser()
+// ...
+// app/(dashboard)/layout.tsx
+const supabase2 = await createClient()   // ⚠ outro client na mesma request
+const { user } = await supabase2.auth.getUser()
+```
+
+**Por quê:** múltiplos `createServerClient` na mesma request podem corromper cookies de refresh de token. Issue [supabase/ssr#68](https://github.com/supabase/ssr/issues/68) — race condition documentada.
+
+**Certo:** middleware faz o refresh **uma vez por request**. Layouts apenas leem o user via `getUser()` que retorna cached:
+```tsx
+// app/layout.tsx — middleware já fez o refresh
+const supabase = await createClient()
+const { data: { user } } = await supabase.auth.getUser()
+```
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — RLS aplicado quando user autenticado consulta tabelas
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — Edge Functions usando service_role server-side
+- [supabase-realtime](../supabase-realtime/SKILL.md) — Realtime exige usuário autenticado para canais privados
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + comandos CLI