@luanpdd/kit-mcp 1.7.0 → 1.9.0

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/burn-rate-alerting/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: burn-rate-alerting
+description: Use ao calcular burn rate predictive — lookahead/baseline window com fator 4×, context-aware vs short-term, fórmula de extrapolação para alert page vs ticket.
+---
+
+# Observabilidade — Burn Rate Alerting
+
+## Quando usar
+
+LLM carrega esta skill ao configurar alertas SLO ou avaliar burn rate. Trigger phrases:
+
+- "burn rate alert", "burn rate forecast"
+- "lookahead window", "baseline window"
+- "predictive vs context-aware"
+- "quando paginar vs quando criar ticket"
+- "extrapolar exhaustão de budget"
+
+## Fórmula canônica
+
+```
+burn_rate = error_rate / (1 - SLO_target)
+```
+
+| Burn rate | Significado |
+|---|---|
+| 1× | Budget durará exatamente a janela do SLO |
+| 2× | Budget acabará em metade da janela |
+| 10× | Budget acabará em 1/10 da janela |
+| 100× | Budget esgotado em horas, não dias |
+
+**Predictive forecast (Cap 13 p145):**
+
+```
+projected_remaining_at_lookahead = current_remaining - (burn_rate_now × lookahead_window)
+ALERT iff projected_remaining_at_lookahead < 0
+```
+
+## Regras absolutas
+
+- **Lookahead ≤ 4× baseline** — extrapolar 4 horas a partir de baseline 1h é confiável; extrapolar 1 dia a partir de 1h é flappy. (Sem ajuste de seasonality)
+- **Sliding window 30d** para o SLO — alinha com customer memory (skill [`event-based-slos`](../skills/event-based-slos/SKILL.md))
+- **2 alertas por SLO** — short-term (page) + long-term (ticket). Não 1 só, não 5+.
+- **Short-term: lookahead 4h, baseline 1h** — paga on-call em horas
+- **Long-term: lookahead 3d, baseline 18h** — abre ticket, não acorda alguém
+- **Context-aware vs short-term** — escolher por trade-off de custo vs sensibilidade. Default short-term para a maioria; context-aware se "10% restante = mais urgente que 90%".
+- **Não alertar zero-level** — se você só alerta quando budget = 0, não há tempo de reagir. Use predictive sempre.
+
+## Patterns canônicos
+
+### Pattern: 2 alertas canônicos por SLO
+
+```yaml
+# PT-BR: para SLO 99.9% checkout_success com window 30d
+slo: checkout_success
+target: 0.999
+window: 30d_sliding
+
+alerts:
+  # PT-BR: PAGE — paginar on-call (urgent)
+  - name: short_term_burn
+    type: predictive
+    lookahead: 4h          # PT-BR: forecast 4h à frente
+    baseline: 1h           # PT-BR: 4× regra (4h ≤ 4× 1h ✓)
+    severity: page
+    threshold_burn_rate: 14.4   # PT-BR: 4h × 14.4 = ~58h, esgota budget de 30d×0.001 = 43.2min em <4h
+    routing: pagerduty:on-call
+  
+  # PT-BR: TICKET — criar ticket Jira/Linear (não-urgent)
+  - name: long_term_burn
+    type: predictive
+    lookahead: 3d
+    baseline: 18h          # PT-BR: 4× regra (3d ≤ 4× 18h = 72h ✓)
+    severity: ticket
+    threshold_burn_rate: 1.0    # PT-BR: 1× = vai esgotar em 30d se continuar
+    routing: jira:engineering
+```
+
+### Pattern: query de burn rate atual (Postgres)
+
+```sql
+-- PT-BR: burn rate atual em janela baseline (último 1h)
+-- Para SLO 99.9% checkout_success
+with baseline as (
+  select
+    sum(good) as good,
+    sum(bad) as bad,
+    sum(total) as total
+  from obs.sli_checkout_success
+  where bucket > now() - interval '1 hour'   -- baseline window
+)
+select
+  total,
+  bad,
+  bad::float / nullif(total, 0) as error_rate,
+  (bad::float / nullif(total, 0)) / (1 - 0.999) as burn_rate,
+  case
+    when bad::float / nullif(total, 0) >= 0.0144 then 'PAGE'   -- burn_rate ≥ 14.4
+    when bad::float / nullif(total, 0) >= 0.001 then 'TICKET'   -- burn_rate ≥ 1
+    else 'OK'
+  end as alert_status
+from baseline;
+```
+
+### Pattern: predictive forecast — esgotamento
+
+```sql
+-- PT-BR: ETA exhaustão do budget em horas
+with current_state as (
+  select
+    sum(case when bucket > now() - interval '30 days' then bad else 0 end) as bad_30d,
+    sum(case when bucket > now() - interval '30 days' then total else 0 end) as total_30d,
+    sum(case when bucket > now() - interval '1 hour' then bad else 0 end) as bad_1h,
+    sum(case when bucket > now() - interval '1 hour' then total else 0 end) as total_1h
+  from obs.sli_checkout_success
+)
+select
+  -- PT-BR: budget restante em eventos
+  (1 - 0.999) * total_30d - bad_30d as remaining_budget,
+  -- PT-BR: taxa atual de queima (eventos/hora)
+  bad_1h::float / 1 as burn_per_hour,
+  -- PT-BR: ETA = budget restante / taxa
+  case
+    when bad_1h = 0 then 'NO_BURN'
+    else round(((1 - 0.999) * total_30d - bad_30d) / nullif(bad_1h, 0))::text || 'h'
+  end as eta_to_exhaustion
+from current_state;
+```
+
+### Pattern: context-aware vs short-term
+
+```text
+SHORT-TERM (cheap):
+  - Olha apenas baseline window (último 1h)
+  - Não considera quanto budget já foi gasto
+  - Mais barato; default para maioria
+  - Pode causar false positive se budget está cheio (90% restante)
+
+CONTEXT-AWARE (expensive):
+  - Considera budget remanescente
+  - "Remaining budget × tolerable_burn_rate ≥ lookahead × current_burn_rate"
+  - Mais caro (query SLO total + recente)
+  - Recomendado para SLOs de alto risco onde 10% restante > 90% restante
+```
+
+### Pattern: dashboard de burn rate (Markdown gerado por `/burn-rate-status`)
+
+```markdown
+# Burn Rate Status — 2026-05-06 14:32 UTC
+
+| SLO | Target | Window | Budget gasto | Burn rate atual | ETA exhaustão | Ação |
+|---|---|---|---|---|---|---|
+| checkout_success | 99.9% | 30d sliding | 23% | 1.4× | 12d | informativo |
+| login_success | 99.95% | 30d sliding | 78% | 8.0× | 4h | **PAGE on-call** |
+| search_latency | 99% | 30d sliding | 15% | 0.7× | — | OK |
+| admin_panel | (sem SLO) | — | — | — | — | — |
+```
+
+### Pattern: tightening alerts gradualmente
+
+```text
+SEMANA 1: SLO + alerts em test channel (não real page)
+SEMANA 2: SLO + alerts em low-priority email
+SEMANA 3-4: validar que SLO detecta incidents reais
+SEMANA 5+: alerts SLO viram primários, threshold antigos para test channel
+SEMANA 8+: deletar threshold antigos completamente
+
+PT-BR: case study Honeycomb (Cap 12 p135) — SLO detectou outage 8h antes
+       de threshold tradicional alertar. Confiança = deletar antigos.
+```
+
+## Anti-patterns
+
+### ANTI: 1 alerta apenas (zero-level)
+
+```text
+ANTI: alert dispara quando budget == 0 (totalmente exausto)
+
+PROBLEMA: você não tem tempo de reagir. Budget zerou, SLO violado, cliente afetado.
+
+CERTO: 2 alertas:
+  - Short-term: burn rate 14.4× → page (4h de runway)
+  - Long-term: burn rate 1× → ticket (3d de runway)
+```
+
+### ANTI: lookahead >> baseline
+
+```text
+ANTI: lookahead 1d a partir de baseline 1h (24×)
+
+PROBLEMA: extrapolação linear de janela curta para janela longa é inválida.
+          Ciclos diários, semanais, sazonalidades distorcem.
+          Alert flappa (entra/sai a cada hora).
+
+CERTO: lookahead ≤ 4× baseline (regra empírica do livro p145)
+       Para alertar 1d à frente: baseline ≥ 6h
+```
+
+### ANTI: burn rate threshold = 1×
+
+```text
+ANTI: page on-call quando burn rate >= 1× (igual à taxa que esgota a janela)
+
+PROBLEMA: 1× sustained durante 1 mês = budget zerou ao final.
+          Time tem 30d para reagir. NÃO é page-worthy.
+
+CERTO: page = 14.4× (esgota em 4h, ação imediata)
+       ticket = 1× (esgota em 30d, ação planejada)
+```
+
+### ANTI: burn rate calculation com janela errada
+
+```text
+ANTI: calcular burn rate sobre janela inteira de SLO (30d)
+
+PROBLEMA: smooth out spikes recentes. Você vê "compliance ok 99.7%" mesmo
+          quando última 1h queimou 30% do budget. Reage tarde.
+
+CERTO: burn rate sobre baseline window (1h ou 18h), comparado ao SLO inteiro
+       para avaliar remaining budget.
+```
+
+### ANTI: ignorar seasonality
+
+```text
+ANTI: alertar 1d à frente sem considerar que sábado tem 1/3 do tráfego
+
+PROBLEMA: false positive sexta à noite (sábado vai ser baixo);
+          false negative segunda de manhã (sábado foi baixo, segunda explode).
+
+CERTO: ou (a) usar baseline window grande o suficiente para capturar 1 ciclo
+            (≥ 24h cobre dia/noite; ≥ 7d cobre semana);
+       ou (b) modelar seasonality (cíclico) — context-aware burn alerts
+            que conhecem padrões.
+```
+
+## Verificação
+
+Antes de promover burn alerts a produção:
+
+1. **2 alertas por SLO** — short-term (page) + long-term (ticket)
+2. **Lookahead ≤ 4× baseline** — verifique aritmética em cada
+3. **Threshold burn rate calculado** — `target=99.9% → page=14.4×, ticket=1×`
+4. **Routing nomeado** — `pagerduty:on-call` ou `jira:engineering`
+5. **Test channel primeiro** — 1+ semana em low-priority antes de promover
+6. **SLO já provou valor** — detectou incident antes de threshold antigo
+7. **Documentação** — runbook de "o que fazer quando alert dispara"
+
+---
+
+## Ver também
+
+- `kit/skills/_shared-observability/glossary.md` — burn rate, lookahead/baseline
+- `kit/skills/event-based-slos/SKILL.md` — SLO definition
+- `kit/skills/core-analysis-loop/SKILL.md` — investigar root cause após alert
+- `kit/agents/burn-rate-forecaster.md` — agente que calcula via SQL
+- `kit/commands/burn-rate-status.md` — comando que invoca forecaster
+
+*Material-fonte: Observability Engineering (O'Reilly, 2022) — Cap 13: "Acting on and Debugging SLO-Based Alerts".*