@luanpdd/kit-mcp 1.7.0 → 1.8.1

package/kit/skills/supabase-postgres-style/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: supabase-postgres-style
+description: Use ao escrever SQL para Postgres/Supabase — snake_case, lowercase reserved, plurais para tabelas e singular para colunas, ISO 8601, CTEs lineares.
+---
+
+# Supabase — Postgres Style Guide
+
+## Quando usar
+
+LLM carrega esta skill quando trabalhar com SQL em projeto Supabase/Postgres — definir schemas, escrever queries, criar tabelas/colunas, padronizar dates, decidir nomes. Trigger phrases:
+
+- "criar tabela em postgres", "create table"
+- "escrever query SQL para Supabase"
+- "estilo de schema", "convenção de nomes em SQL"
+- "estrutura de query complexa" (CTE vs subquery)
+
+## Regras absolutas
+
+- **Sempre** use **`lowercase reserved`** words: `select`, `from`, `where`, `join`, `with`, `as`. **Nunca** `SELECT`, `FROM`, `WHERE` em maiúscula.
+- **Sempre** use **`snake_case`** para tabelas, colunas, funções, índices. **Nunca** `camelCase` ou `PascalCase`.
+- **Tabelas em plural** (`books`, `authors`, `users`); **colunas em singular** (`title`, `author_id`, `created_at`).
+- **Datas em `ISO 8601`** com timezone: `timestamptz` (não `timestamp` sem tz). String literal: `'2026-05-06T12:00:00Z'`.
+- Aliases descritivos com `as` **explícito**: `select b.title as book_title from books as b`. Nunca alias implícito.
+- Evite `id` ambíguo. Em FKs use `<entity>_id` (`author_id`, `user_id`). Em PKs use `id` apenas se a tabela já é singular contextualmente.
+- Para queries complexas: prefira **múltiplas CTEs lineares** sobre subqueries aninhadas. Cada CTE com 1 propósito + comentário.
+- JOINs sempre com nomes completos da tabela qualificadora: `books.author_id = authors.id` (não aliases curtos como `b.x = a.y` sem `as`).
+
+## Patterns canônicos
+
+### Tabela típica
+
+```sql
+-- estilo: lowercase reserved + snake_case + tabela em plural + colunas em singular
+create table public.books (
+  id uuid primary key default gen_random_uuid(),
+  title text not null,
+  author_id uuid references public.authors (id) on delete cascade,
+  published_at timestamptz,                       -- ISO 8601 com timezone
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+-- comentário descritivo na tabela (até 1024 chars)
+comment on table public.books is 'Catálogo de livros disponíveis na biblioteca.';
+```
+
+### Query simples (uma linha por cláusula)
+
+```sql
+-- query curta: pode ficar em poucas linhas
+select id, title, author_id
+  from public.books
+  where published_at is not null
+  order by published_at desc
+  limit 50;
+```
+
+### Query complexa com CTEs lineares
+
+```sql
+-- preferir CTEs lineares — cada uma com 1 propósito
+with recent_books as (
+  -- 1. livros publicados nos últimos 30 dias
+  select id, title, author_id, published_at
+    from public.books
+    where published_at >= now() - interval '30 days'
+),
+author_stats as (
+  -- 2. agregação por autor sobre os livros recentes
+  select author_id, count(*) as total_recent
+    from recent_books
+    group by author_id
+)
+select a.name as author_name, s.total_recent
+  from author_stats as s
+  join public.authors as a on a.id = s.author_id
+  order by s.total_recent desc;
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Reserved words em maiúscula + mixed case
+
+**Errado:**
+```sql
+SELECT * FROM Books WHERE Title='X'
+```
+
+**Por quê:** vai contra convenção da comunidade Postgres + dificulta diff em pull requests. Identificadores `Books` exigirão quoting (`"Books"`) sempre, ou o Postgres dobra para `books` quietly.
+
+**Certo:**
+```sql
+select * from books where title = 'X'
+```
+
+### Anti-pattern 2: `timestamp` sem timezone + camelCase
+
+**Errado:**
+```sql
+create table users (
+  id int primary key,
+  createdAt timestamp,                    -- sem timezone
+  fullName text                           -- camelCase
+);
+```
+
+**Por quê:** `timestamp` (sem `tz`) não preserva timezone — converte tudo para o timezone do servidor; ambíguo em apps multi-região. `camelCase` em SQL é estilizado por engine driver (caso por caso) e quebra em ferramentas que esperam snake_case.
+
+**Certo:**
+```sql
+create table users (
+  id uuid primary key default gen_random_uuid(),
+  created_at timestamptz not null default now(),
+  full_name text
+);
+```
+
+### Anti-pattern 3: subqueries aninhadas em vez de CTEs
+
+**Errado:**
+```sql
+select * from (
+  select author_id, count(*) from (
+    select * from books where published_at > now() - interval '30 days'
+  ) recent group by author_id
+) ranked where count > 5;
+```
+
+**Por quê:** ilegível, impossível de comentar cada nível, query plan harder to read.
+
+**Certo:** ver "Query complexa com CTEs lineares" acima.
+
+## Ver também
+
+- [supabase-migrations](../supabase-migrations/SKILL.md) — estilo aplicado em arquivos de migration
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — estilo aplicado em funções Postgres
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — convenção de naming em policies
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + comandos CLI canônicos

package/kit/skills/supabase-realtime/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: supabase-realtime
+description: Use ao implementar Realtime — broadcast com private:true, naming scope:entity:id, RLS sobre realtime.messages, removeChannel cleanup, migrar de postgres_changes.
+---
+
+# Supabase — Realtime
+
+## Quando usar
+
+LLM carrega esta skill quando implementar features Realtime em Supabase (chat, presence, notifications, live dashboards). Trigger phrases:
+
+- "Supabase Realtime", "broadcast", "presence"
+- "subscrever a mudanças no banco em tempo real"
+- "WebSocket Supabase"
+- "migrar postgres_changes para broadcast"
+- "RLS realtime.messages"
+- "channel state", "removeChannel"
+
+## Regras absolutas
+
+- **Use `broadcast` por default** — `postgres_changes` é pattern legado (single-threaded, não escala). **Migrar para broadcast** em features novas.
+- **`private: true`** em todos os canais novos — exige autenticação + RLS sobre `realtime.messages`. Default em produção 2026.
+- **Naming canônico `scope:entity:id`** — ex: `room:messages:abc123`, `user:notifications:xyz789`, `org:announcements:org_42`.
+- **Eventos em `entity_action`** — ex: `message_inserted`, `task_updated`, `presence_joined`.
+- **`removeChannel` no cleanup obrigatório** — chamar `supabase.removeChannel(channel)` em `useEffect return` ou equivalente. Sem cleanup, memory leak + stale state (anti-pitfall B1).
+- **State checking antes de subscribe** — `if (channel.state === 'joined') return;` evita double-subscribe.
+- **RLS sobre `realtime.messages`** — SELECT (read) e INSERT (write) policies separadas, com index nas colunas usadas.
+- **Use Presence com moderação** — apenas para online status / cursors colaborativos, não para listas de objects (use queries normais).
+- Realtime tem **retry built-in** — log `status` no callback do `subscribe` mas não implementar retry manual.
+
+## Patterns canônicos
+
+### Subscribe via broadcast — client com cleanup
+
+```ts
+// PT-BR: subscrição típica em Client Component
+'use client'
+import { useEffect, useState } from 'react'
+import { createClient } from '@/utils/supabase/client'
+
+export function ChatRoom({ roomId }: { roomId: string }) {
+  const supabase = createClient()
+  const [messages, setMessages] = useState<Message[]>([])
+
+  useEffect(() => {
+    const channel = supabase
+      .channel(`room:messages:${roomId}`, { config: { private: true } })
+      .on('broadcast', { event: 'message_inserted' }, ({ payload }) => {
+        setMessages((prev) => [...prev, payload as Message])
+      })
+      .subscribe((status) => {
+        if (status === 'SUBSCRIBED') console.log('joined channel')
+        if (status === 'CHANNEL_ERROR') console.error('channel error')
+      })
+
+    // PT-BR: cleanup obrigatório — sem isso, memory leak
+    return () => {
+      supabase.removeChannel(channel)
+    }
+  }, [roomId, supabase])
+
+  return <ul>{messages.map((m) => <li key={m.id}>{m.text}</li>)}</ul>
+}
+```
+
+### RLS sobre `realtime.messages`
+
+```sql
+-- PT-BR: SELECT policy permite ouvir broadcast em canal autenticado
+-- Granular: SELECT = read, INSERT = write — duas policies separadas
+create policy "auth_select_realtime_messages"
+  on realtime.messages
+  for select
+  to authenticated
+  using ((select auth.uid()) is not null);
+
+-- PT-BR: INSERT policy permite enviar broadcast
+create policy "auth_insert_realtime_messages"
+  on realtime.messages
+  for insert
+  to authenticated
+  with check ((select auth.uid()) is not null);
+
+-- PT-BR: index obrigatório (extension é a coluna usada por broadcast)
+create index if not exists realtime_messages_extension_idx
+  on realtime.messages (extension);
+```
+
+### DB trigger via `realtime.broadcast_changes`
+
+Para emitir broadcast quando linha de tabela muda (substitui `postgres_changes`):
+
+```sql
+-- PT-BR: trigger function emite broadcast no canal scope:entity:id
+create or replace function public.notify_message_insert()
+returns trigger
+language plpgsql
+security invoker
+set search_path = ''
+as $$
+begin
+  perform realtime.broadcast_changes(
+    'room:messages:' || new.room_id::text,    -- canal
+    'message_inserted',                        -- event name
+    'INSERT',                                  -- operation
+    'messages',                                -- table
+    'public',                                  -- schema
+    new,                                       -- new row
+    null                                       -- old row
+  );
+  return new;
+end;
+$$;
+
+create trigger messages_broadcast_on_insert
+  after insert on public.messages
+  for each row
+  execute function public.notify_message_insert();
+```
+
+### Presence — apenas para online status
+
+```ts
+// PT-BR: presence é sparingly — só para "quem está online"
+const channel = supabase
+  .channel(`room:${roomId}`, { config: { private: true } })
+  .on('presence', { event: 'sync' }, () => {
+    const state = channel.presenceState()
+    setOnlineUsers(Object.keys(state))
+  })
+  .subscribe(async (status) => {
+    if (status !== 'SUBSCRIBED') return
+    await channel.track({ user_id: userId, online_at: new Date().toISOString() })
+  })
+
+return () => {
+  supabase.removeChannel(channel)
+}
+```
+
+### Migrar de `postgres_changes` para `broadcast`
+
+```ts
+// ❌ PADRÃO LEGADO — postgres_changes
+const channel = supabase
+  .channel('messages_changes')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, callback)
+  .subscribe()
+
+// ✅ PADRÃO ATUAL — broadcast com trigger DB
+// 1. Criar trigger SQL `realtime.broadcast_changes` (ver pattern acima)
+// 2. Subscribe via broadcast no client:
+const channel = supabase
+  .channel(`room:messages:${roomId}`, { config: { private: true } })
+  .on('broadcast', { event: 'message_inserted' }, callback)
+  .subscribe()
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Canal sem `private: true`
+
+**Errado:**
+```ts
+const channel = supabase.channel('messages')                  // canal público
+  .on('broadcast', { event: 'msg' }, callback)
+  .subscribe()
+```
+
+**Por quê:** canal público — qualquer cliente recebe payload sem RLS. Em produção isso vaza dados (broadcast pode incluir info sensível).
+
+**Certo:**
+```ts
+const channel = supabase
+  .channel(`room:messages:${roomId}`, { config: { private: true } })
+  .on('broadcast', { event: 'message_inserted' }, callback)
+  .subscribe()
+```
+
+### Anti-pattern 2: Subscribe sem `removeChannel` no cleanup
+
+**Errado:**
+```tsx
+useEffect(() => {
+  const channel = supabase.channel('...').subscribe()
+  // ⚠ sem return — canal nunca limpo
+}, [])
+```
+
+**Por quê:** memory leak. Em SPA com navegação, canais antigos continuam recebendo eventos — UI fica em estado inconsistente. WebSocket connections crescem indefinidamente.
+
+**Certo:**
+```tsx
+useEffect(() => {
+  const channel = supabase.channel('...').subscribe()
+  return () => {
+    supabase.removeChannel(channel)
+  }
+}, [])
+```
+
+### Anti-pattern 3: `postgres_changes` em features novas
+
+**Errado:**
+```ts
+supabase.channel('changes')
+  .on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, callback)
+  .subscribe()
+```
+
+**Por quê:** `postgres_changes` é single-threaded em Realtime backend. Em escala (>100 connections, >1k events/sec), throughput cai drasticamente. Documentado em [Realtime Limits](https://supabase.com/docs/guides/realtime/limits).
+
+**Certo:** trigger DB com `realtime.broadcast_changes` + subscribe via `broadcast` (ver pattern "Migrar" acima).
+
+### Anti-pattern 4: Presence para listar objetos
+
+**Errado:**
+```ts
+// ⚠ usar presence para listar tasks ativas
+channel.on('presence', { event: 'sync' }, () => {
+  const tasks = Object.values(channel.presenceState())
+  setTasks(tasks)
+})
+```
+
+**Por quê:** Presence é projetado para "quem está online" — state efêmero ligado a connection. Para listas de objetos, use query normal + broadcast quando muda. Presence inflado degrada toda a infraestrutura Realtime do projeto.
+
+**Certo:** query SQL para `tasks` + broadcast em mudanças via trigger DB.
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — RLS sobre `realtime.messages` (SELECT + INSERT separados)
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — trigger functions com `set search_path = ''`
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — autenticação que habilita canais `private: true`
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — Edge Functions disparando broadcast via `realtime.send`
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN

package/kit/skills/supabase-rls-policies/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: supabase-rls-policies
+description: Use ao criar/auditar RLS — sempre (select auth.uid()), policies separadas por operação, índices nas colunas, NUNCA user_metadata em autorização.
+---
+
+# Supabase — RLS Policies
+
+## Quando usar
+
+LLM carrega esta skill quando criar, auditar ou debugar Row Level Security em Supabase. Trigger phrases:
+
+- "criar policy RLS", "RLS policy", "row level security"
+- "policies separadas por operação"
+- "auth.uid()", "auth.jwt()"
+- "MFA enforcement", "AAL2"
+- "auditar segurança de tabela Supabase"
+
+## Regras absolutas
+
+**WARNING — REGRA #1 (segurança crítica):** **NUNCA** referencie `user_metadata` em policy de autorização. `user_metadata` é editável pelo cliente via `auth.updateUser({data: {...}})` — usuário pode auto-elevar `role: 'admin'` ou `plan: 'premium'`. Use **`app_metadata`** (set apenas via service_role) para roles/permissions.
+
+**REGRA #2 (performance crítica):** **SEMPRE** envolva `auth.uid()` em `(select auth.uid())`. Sem o wrapper, Postgres reavalia a função **uma vez por linha** — degrada queries com filtro RLS em **até 1000×**.
+
+**Outras regras:**
+
+- **`policies separadas por operação`** — uma `for select`, uma `for insert`, uma `for update`, uma `for delete`. **Nunca** `for all` cobrindo CRUD inteiro.
+- **`TO authenticated`** ou **`to anon`** sempre explícito — nunca deixar implícito (default `to public` é insecure).
+- `for select` e `for delete` usam **apenas `using`** (sem `with check`).
+- `for insert` usa **apenas `with check`** (sem `using`).
+- `for update` usa **`using` + `with check`** (using para qual linha pode ser atualizada, with check para qual estado a linha pode assumir).
+- Índice obrigatório nas colunas referenciadas pela policy: `create index on public.tasks (user_id);`. Sem index, scan full em cada query.
+- `permissive` é default e preferido. `restrictive` é raro e exige justificativa explícita.
+- Para MFA enforcement: `(auth.jwt()->>'aal')::text = 'aal2'` em policies que exigem 2FA ativo.
+
+## Patterns canônicos
+
+### SELECT — usuário lê apenas suas próprias linhas
+
+```sql
+-- política de SELECT com wrapper (select auth.uid()) obrigatório
+create policy "users_select_own_tasks"
+  on public.tasks
+  for select
+  to authenticated
+  using ((select auth.uid()) = user_id);
+
+-- index obrigatório (sem isso, scan full)
+create index tasks_user_id_idx on public.tasks (user_id);
+```
+
+### INSERT, UPDATE, DELETE separados
+
+```sql
+-- INSERT — usuário só pode criar linhas com user_id = ele mesmo
+create policy "users_insert_own_tasks"
+  on public.tasks
+  for insert
+  to authenticated
+  with check ((select auth.uid()) = user_id);
+
+-- UPDATE — restringe quais linhas (using) E qual estado novo (with check)
+create policy "users_update_own_tasks"
+  on public.tasks
+  for update
+  to authenticated
+  using ((select auth.uid()) = user_id)
+  with check ((select auth.uid()) = user_id);
+
+-- DELETE — apenas a coluna using (sem with check)
+create policy "users_delete_own_tasks"
+  on public.tasks
+  for delete
+  to authenticated
+  using ((select auth.uid()) = user_id);
+```
+
+### Role admin via `app_metadata`
+
+```sql
+-- segurança: app_metadata é set apenas via service_role (admin API)
+-- cliente NÃO pode mutá-lo
+create policy "admins_manage_all_tasks"
+  on public.tasks
+  for update
+  to authenticated
+  using (
+    (select auth.jwt()->'app_metadata'->>'role') = 'admin'
+  )
+  with check (
+    (select auth.jwt()->'app_metadata'->>'role') = 'admin'
+  );
+```
+
+### MFA enforcement (AAL2)
+
+```sql
+-- exigir 2FA ativo para acessar dados sensíveis
+create policy "mfa_required_for_billing"
+  on public.billing_records
+  for select
+  to authenticated
+  using (
+    (select (auth.jwt()->>'aal')::text) = 'aal2'
+    and (select auth.uid()) = user_id
+  );
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: `auth.uid()` sem `(select)` wrapper
+
+**Errado:**
+```sql
+create policy "users_select_own_tasks"
+  on public.tasks
+  for select
+  to authenticated
+  using (auth.uid() = user_id);            -- sem (select) — re-executa por linha
+```
+
+**Por quê:** Postgres reavalia `auth.uid()` para cada linha sendo testada. Em tabela com 100k linhas, isso é 100k chamadas. O `(select)` permite Postgres executar **uma vez** e reusar — degradação de até **1000×** sem o wrapper. Documentado em [RLS Performance](https://supabase.com/docs/guides/troubleshooting/rls-performance-and-best-practices-Z5Jjwv).
+
+**Certo:**
+```sql
+using ((select auth.uid()) = user_id)
+```
+
+### Anti-pattern 2: `WARNING user_metadata` em autorização — privilege escalation
+
+**Errado:**
+```sql
+create policy "admins_manage_all"
+  on public.tasks
+  for update
+  to authenticated
+  using (
+    (auth.jwt()->'user_metadata'->>'role') = 'admin'   -- editável pelo cliente!
+  );
+```
+
+**Por quê:** o cliente pode chamar `supabase.auth.updateUser({ data: { role: 'admin' } })` e instantaneamente ganhar privilégios de admin. `user_metadata` é projetado para preferences do usuário (tema, idioma), não para autorização. Documentado em [Splinter linter 0015](https://supabase.github.io/splinter/0015_rls_references_user_metadata/).
+
+**Certo:** ver "Role admin via `app_metadata`" acima — `app_metadata` requer service_role para mutar.
+
+### Anti-pattern 3: `for all` em vez de policies granulares
+
+**Errado:**
+```sql
+create policy "users_manage_own_tasks"
+  on public.tasks
+  for all                                  -- cobre CRUD inteiro com mesma regra
+  to authenticated
+  using ((select auth.uid()) = user_id);
+```
+
+**Por quê:** semântica de `for all` mistura `using` (que controla SELECT/UPDATE/DELETE) com `with check` (que controla INSERT/UPDATE), levando a confusão. Em UPDATE você pode querer regras diferentes para "qual linha tocar" vs "qual estado novo". Granularidade explícita previne erros sutis.
+
+**Certo:** ver pattern com 4 policies separadas acima (SELECT, INSERT, UPDATE, DELETE).
+
+### Anti-pattern 4: Sem índice nas colunas da policy
+
+**Errado:**
+```sql
+-- policy referencia user_id mas não há index
+create policy "users_select_own_tasks" on public.tasks
+  for select to authenticated
+  using ((select auth.uid()) = user_id);
+
+-- (esqueceu) create index on public.tasks (user_id);
+```
+
+**Por quê:** cada query com filtro RLS força sequential scan. Em produção com 100k+ linhas, isso é lentidão crônica.
+
+**Certo:**
+```sql
+create index tasks_user_id_idx on public.tasks (user_id);
+```
+
+## Ver também
+
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — funções com `set search_path = ''` que respeitam RLS
+- [supabase-storage](../supabase-storage/SKILL.md) — RLS sobre `storage.objects` (multi-tenant path isolation)
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — autenticação que popula `auth.uid()`
+- [supabase-migrations](../supabase-migrations/SKILL.md) — migrations sempre com RLS habilitado em novas tabelas
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + roles + comandos CLI