@luanpdd/kit-mcp 1.7.0 → 1.9.0

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

@@ -0,0 +1,175 @@
+---
+name: supabase-migrations
+description: Use ao criar arquivos de migration Supabase — naming YYYYMMDDHHmmss_short.sql, header de metadados, RLS obrigatório em toda nova tabela, granular policies.
+---
+
+# Supabase — Migrations
+
+## Quando usar
+
+LLM carrega esta skill quando criar/editar arquivos em `supabase/migrations/`. Trigger phrases:
+
+- "criar migration Supabase", "supabase migration new"
+- "alterar schema do banco", "alter table"
+- "criar nova tabela em Postgres/Supabase"
+- "adicionar coluna a tabela existente"
+- "drop column / drop table" (operações destrutivas — exige cuidado extra)
+
+## Regras absolutas
+
+- **Naming canônico:** `YYYYMMDDHHmmss_short_description.sql` em UTC (ex: `20260506120000_create_tasks.sql`). Use `supabase migration new <name>` para gerar timestamp correto.
+- **Header de metadados** no topo de cada migration (block comment) descrevendo Migration / Created / Purpose / Affects.
+- **lowercase em todo SQL** (alinhado com `supabase-postgres-style`).
+- **Comentários copiosos** em comandos destrutivos: `drop table`, `drop column`, `alter table ... drop column`, `truncate`, `delete from` em massa. Comentário explica o porquê + impacto.
+- **`RLS` obrigatório em toda nova tabela** — `alter table public.<name> enable row level security;` no mesmo arquivo da criação.
+- **`granular policies`** — uma `for select`, uma `for insert`, uma `for update`, uma `for delete`. **Nunca** `for all`.
+- **`(select auth.uid())`** sempre wrapped (REGRA #1 de RLS).
+- **Index nas colunas referenciadas por RLS:** `create index on public.<table> (user_id);` no mesmo arquivo.
+- Idempotência onde possível: `create table if not exists`, `create index if not exists`. Migrations rodam em ordem mas tooling pode re-executar.
+- Migrations são **append-only**. Para reverter, criar nova migration que desfaz — nunca editar migration já aplicada.
+
+## Patterns canônicos
+
+### Criar tabela com RLS + policies granulares + index
+
+```sql
+/*
+  Migration: create_tasks
+  Created: 2026-05-06
+  Purpose: Cria tabela tasks com RLS habilitado e policies granulares por operação.
+  Affects: public.tasks (new), public.tasks policies (new — 4 policies)
+*/
+
+create table if not exists public.tasks (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  title text not null,
+  status text not null default 'todo',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+alter table public.tasks enable row level security;
+
+-- granular policies: uma por operação por role
+create policy "users_select_own_tasks"
+  on public.tasks for select to authenticated
+  using ((select auth.uid()) = user_id);
+
+create policy "users_insert_own_tasks"
+  on public.tasks for insert to authenticated
+  with check ((select auth.uid()) = user_id);
+
+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);
+
+create policy "users_delete_own_tasks"
+  on public.tasks for delete to authenticated
+  using ((select auth.uid()) = user_id);
+
+-- index obrigatório nas colunas usadas pela policy
+create index if not exists tasks_user_id_idx on public.tasks (user_id);
+```
+
+### Adicionar coluna a tabela existente
+
+```sql
+/*
+  Migration: add_priority_to_tasks
+  Created: 2026-05-06
+  Purpose: Adiciona coluna priority (low/medium/high) a tasks com default low.
+  Affects: public.tasks (column added — non-destructive)
+*/
+
+alter table public.tasks
+  add column if not exists priority text not null default 'low';
+
+-- check constraint para enum-like
+alter table public.tasks
+  add constraint tasks_priority_check
+  check (priority in ('low', 'medium', 'high'));
+```
+
+### Operação destrutiva — drop column com comentário extensivo
+
+```sql
+/*
+  Migration: drop_legacy_subtitle_column
+  Created: 2026-05-06
+  Purpose: Remove coluna subtitle (deprecated em v3.0 — nunca foi usada em produção).
+  Affects: public.tasks (column dropped — DESTRUCTIVE)
+  Risk: Baixo — coluna nullable nunca populada (validado via select count(*) where subtitle is not null = 0).
+  Rollback: criar nova migration `add subtitle column` se necessário.
+*/
+
+-- DROP de coluna deprecated. Validado upstream: zero linhas com valor não-null.
+-- Operação destrutiva — irreversível sem backup.
+alter table public.tasks
+  drop column if exists subtitle;
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Criar tabela sem RLS
+
+**Errado:**
+```sql
+create table public.tasks (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null,
+  title text not null
+);
+-- esqueceu enable row level security
+```
+
+**Por quê:** sem RLS, tabela exposta ao role `anon` e `authenticated` sem filtro — qualquer cliente lê tudo. RLS habilitado sem policies bloqueia tudo (mais seguro como default que deixar aberto).
+
+**Certo:** sempre `alter table public.tasks enable row level security;` + policies granulares no mesmo arquivo.
+
+### Anti-pattern 2: `for all` em vez de granular policies
+
+**Errado:**
+```sql
+create policy "users_manage_tasks" on public.tasks
+  for all to authenticated
+  using ((select auth.uid()) = user_id);
+```
+
+**Por quê:** mistura `using` (controla SELECT/UPDATE/DELETE) com `with check` (controla INSERT/UPDATE) — em UPDATE você pode querer regras diferentes para "qual linha tocar" vs "qual estado novo".
+
+**Certo:** 4 policies separadas (uma por operação) — ver pattern "Criar tabela" acima.
+
+### Anti-pattern 3: `drop column` sem comentário
+
+**Errado:**
+```sql
+alter table public.tasks drop column legacy_field;
+```
+
+**Por quê:** futuros leitores não sabem por que a coluna foi removida; rollback fica difícil; risk não documentado.
+
+**Certo:** comentário no header explica Purpose + Affects + Risk + Rollback (ver pattern destrutivo acima).
+
+### Anti-pattern 4: `auth.uid()` sem `(select)` wrapper
+
+**Errado:**
+```sql
+using (auth.uid() = user_id)
+```
+
+**Por quê:** degradação 1000× em queries com filtro RLS (Postgres reavalia por linha).
+
+**Certo:**
+```sql
+using ((select auth.uid()) = user_id)
+```
+
+## Ver também
+
+- [supabase-postgres-style](../supabase-postgres-style/SKILL.md) — convenção de naming + style aplicada
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — granular policies + WARNING user_metadata
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — funções com `set search_path = ''`
+- [supabase-declarative-schema](../supabase-declarative-schema/SKILL.md) — workflow alternativo (declarative-first → diff)
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + comandos CLI

package/kit/skills/supabase-pgvector-rag/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: supabase-pgvector-rag
+description: Use ao implementar RAG com pgvector — create extension vector, dim consistente, HNSW vs IVFFlat, operadores <=>/<#>, RAG with permissions via RLS, chunking.
+---
+
+# Supabase — pgvector + RAG
+
+## Quando usar
+
+LLM carrega esta skill quando implementar embeddings, similarity search ou RAG (Retrieval-Augmented Generation) com Supabase. Trigger phrases:
+
+- "pgvector", "vector embeddings"
+- "RAG Supabase", "retrieval augmented generation"
+- "semantic search Postgres"
+- "HNSW vs IVFFlat"
+- "embedding dimension"
+- "match_documents function"
+
+## Regras absolutas
+
+- **Setup:** `create extension if not exists vector;` em migration ou `supabase/schemas/`.
+- **Dimension fixa por modelo** — defina `embedding vector(N)` com N = dim do modelo: 1536 (OpenAI ada-002), 768 (nomic-embed-text), 384 (all-MiniLM-L6-v2). Mismatch = silent fail ou matches aleatórios.
+- **Index obrigatório** — sem index, similarity search faz full scan e degrada drasticamente em > 10k linhas.
+- **`HNSW`** = default em 2026 — recall melhor, queries mais rápidas com mais data. Build mais lento.
+- **`IVFFlat`** = alternativa quando build time domina (datasets dinâmicos com re-build frequente). Recall menor.
+- **Distance operators canônicos:**
+  - **`<=>`** — cosine distance (mais comum em embeddings normalizados)
+  - **`<#>`** — negative inner product
+  - **`<->`** — L2 (euclidean) distance
+- **`RAG with permissions`** — combine similarity search com RLS na tabela source. Sem isso, retrieval vaza documents entre tenants.
+- **Chunking:** 200-500 tokens com overlap 10-20%. Chunks > 1k tokens degradam embeddings; < 100 perdem contexto.
+- **Embedding generation server-side** — geração via Edge Function ou worker (model API key não vai para client).
+
+## Patterns canônicos
+
+### Schema com RLS + HNSW index
+
+```sql
+-- PT-BR: extension uma vez por projeto
+create extension if not exists vector;
+
+-- PT-BR: documents com embedding e user_id para RAG with permissions
+create table public.documents (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  content text not null,                    -- PT-BR: chunk de texto (200-500 tokens)
+  embedding vector(1536) not null,          -- PT-BR: dim casa com modelo
+  metadata jsonb default '{}'::jsonb,
+  created_at timestamptz default now()
+);
+
+-- PT-BR: HNSW com cosine distance (default 2026)
+create index documents_embedding_hnsw_idx
+  on public.documents
+  using hnsw (embedding vector_cosine_ops);
+
+-- PT-BR: RLS — RAG with permissions
+alter table public.documents enable row level security;
+
+create policy "users_read_own_docs"
+  on public.documents for select to authenticated
+  using ((select auth.uid()) = user_id);
+
+create policy "users_insert_own_docs"
+  on public.documents for insert to authenticated
+  with check ((select auth.uid()) = user_id);
+
+create index documents_user_id_idx on public.documents (user_id);
+```
+
+### Função `match_documents` — RAG with permissions
+
+```sql
+create or replace function public.match_documents(
+  query_embedding vector(1536),
+  match_threshold float,
+  match_count int
+)
+returns table (
+  id uuid,
+  content text,
+  similarity float,
+  metadata jsonb
+)
+language plpgsql
+security invoker                            -- PT-BR: invoker → respeita RLS do caller
+set search_path = ''
+stable
+as $$
+begin
+  return query
+    select
+      d.id,
+      d.content,
+      1 - (d.embedding <=> query_embedding) as similarity,
+      d.metadata
+    from public.documents as d
+    where 1 - (d.embedding <=> query_embedding) > match_threshold
+    order by d.embedding <=> query_embedding
+    limit match_count;
+end;
+$$;
+```
+
+**Por que `security invoker`:** garante que a função só retorna documentos que o caller (usuário autenticado) tem permissão de ver via RLS. Sem RLS, qualquer caller via similarity recupera documents de outros tenants.
+
+### Uso da função do client
+
+```ts
+// PT-BR: gerar embedding (em Edge Function, server-side) e chamar match_documents
+const queryEmbedding = await embedQuery(userQuestion)   // dim 1536
+
+const { data: matches } = await supabase.rpc('match_documents', {
+  query_embedding: queryEmbedding,
+  match_threshold: 0.78,
+  match_count: 10,
+})
+
+// matches: [{ id, content, similarity, metadata }, ...] já filtrado por RLS
+const context = matches.map((m) => m.content).join('\n\n')
+const answer = await llmComplete({ context, question: userQuestion })
+```
+
+### IVFFlat alternativa
+
+```sql
+-- PT-BR: usar IVFFlat quando build time importa (dataset dinâmico)
+-- lists = sqrt(N) é heurística para N total de linhas
+create index documents_embedding_ivfflat_idx
+  on public.documents
+  using ivfflat (embedding vector_cosine_ops)
+  with (lists = 100);                       -- ajustar conforme volume
+```
+
+### Geração de embeddings em Edge Function
+
+```ts
+// supabase/functions/embed-document/index.ts
+// PT-BR: chunking + embedding + insert
+import { createClient } from 'npm:@supabase/supabase-js@2'
+import OpenAI from 'npm:openai@4'
+
+Deno.serve(async (req) => {
+  const { user_id, document } = await req.json()
+  const openai = new OpenAI({ apiKey: Deno.env.get('OPENAI_API_KEY') })
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SECRET_KEYS')!
+  )
+
+  // PT-BR: chunk em pedaços de ~400 tokens com overlap 20%
+  const chunks = chunkText(document, { size: 400, overlap: 80 })
+
+  for (const chunk of chunks) {
+    const embedRes = await openai.embeddings.create({
+      model: 'text-embedding-3-small',      // dim 1536
+      input: chunk,
+    })
+    await supabase.from('documents').insert({
+      user_id,
+      content: chunk,
+      embedding: embedRes.data[0].embedding,
+    })
+  }
+
+  return new Response('embedded')
+})
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Dim mismatch entre modelo e coluna
+
+**Errado:**
+```sql
+create table documents (embedding vector(1536) not null);
+```
+```ts
+// PT-BR: usa nomic-embed-text que retorna dim 768
+const embedding = await nomicEmbed(text)              // 768
+await supabase.from('documents').insert({ embedding })  // ⚠ insert falha
+```
+
+**Por quê:** Postgres rejeita insert com dim mismatch (`expected 1536 dimensions, got 768`). Em pior caso, se aceito, similarity retorna ranking aleatório.
+
+**Certo:** alinhe dim:
+```sql
+create table documents (embedding vector(768) not null);
+```
+ou troque o modelo para um que retorne 1536.
+
+### Anti-pattern 2: Similarity search sem RLS — vazamento RAG
+
+**Errado:**
+```sql
+-- PT-BR: tabela documents sem RLS
+create table public.documents (
+  id uuid primary key,
+  content text,
+  embedding vector(1536)
+);
+```
+
+**Por quê:** qualquer authenticated chama `match_documents` e recupera documents de outros usuários. Em apps multi-tenant, é vazamento crítico — RAG do tenant A vê docs do tenant B.
+
+**Certo:** habilite RLS + policies por `user_id`/`org_id` + use `security invoker` em funções de match (ver pattern canônico).
+
+### Anti-pattern 3: Chunks gigantes (> 1k tokens)
+
+**Errado:**
+```ts
+// PT-BR: chunk inteiro de documento (5k tokens)
+const chunks = [fullDocument]
+const embedding = await embed(fullDocument)
+```
+
+**Por quê:** embeddings perdem detalhe semântico em chunks muito grandes. O modelo média muitos conceitos em um único vetor, similarity vira ruidosa. Ranking RAG fica ruim.
+
+**Certo:** chunks de 200-500 tokens com overlap:
+```ts
+const chunks = chunkText(fullDocument, { size: 400, overlap: 80 })
+for (const chunk of chunks) {
+  await embed(chunk).then(insert)
+}
+```
+
+### Anti-pattern 4: Sem index em coluna `embedding`
+
+**Errado:**
+```sql
+create table documents (embedding vector(1536) not null);
+-- (esqueceu create index)
+```
+
+**Por quê:** sem index, similarity search vira sequential scan. Em > 10k linhas, queries levam segundos a minutos. Em produção, app fica inviável.
+
+**Certo:**
+```sql
+create index documents_embedding_hnsw_idx on documents using hnsw (embedding vector_cosine_ops);
+```
+
+## Notas de futuro
+
+- **Hybrid search** (FTS + vector com RRF — Reciprocal Rank Fusion) está coberto em skill `supabase-fts` (defer v1.9 — full-text search standalone).
+- **Vector Buckets** e **Analytics Buckets** ainda em alpha em 2026 — mencione como existência mas não detalhe (pattern canônico evoluindo).
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — RLS é base de RAG with permissions
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — função `match_documents` com `security invoker` + `set search_path = ''`
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — geração de embeddings server-side
+- [supabase-migrations](../supabase-migrations/SKILL.md) — schema com `vector` extension
+- [glossário](../_shared-supabase/glossary.md) — operadores `<=>`/`<#>`/`<->`

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