InsForge Debug

O que InsForge Debug faz?

Diagnosticar problemas em projetos InsForge combinando as primitivas de observabilidade do backend — logs, métricas, integridade do banco de dados (db-health), conselheiro (advisor), políticas, metadados, objetos de erro, estado de implantação e assistência de IA. Esta habilidade fornece:

1. Uma referência por primitiva de depuração (cada superfície de observabilidade — em references/)
2. Receitas de sintomas (abaixo) que nomeiam a sequência de primitivas para sintomas reativos conhecidos e auditorias proativas

Sempre use npx -y @insforge/cli — nunca instale a CLI globalmente.

Caminho Mais Rápido: Triagem Assistida por IA

Quando o usuário fornece uma descrição concreta (mensagem de erro, URL com falha, status HTTP), passe-a para o agente de depuração do InsForge. Diferente das outras primitivas, este agente retorna sugestões, não apenas observações — verifique o diagnóstico com base nas primitivas que ele cita antes de agir.

npx -y @insforge/cli diagnose --ai "<descrição do problema>"

Veja references/ai-assisted.md para saber quando usar esta opção primeiro vs. quando pular, e como verificar a saída.

Primitivas de Depuração

Cada primitiva é uma superfície de observabilidade consultável independentemente, apoiada por uma fonte de dados subjacente distinta. Diagnósticos reais são composições de primitivas.

Todos os comandos são executados via npx -y @insforge/cli .... O (comando) mostrado ao lado de cada primitiva é o comando CLI real — os nomes das primitivas são rótulos conceituais, não nomes de subcomandos CLI (por exemplo, "DB health" é diagnose db, não diagnose db-health; "Policies" é db policies, não diagnose policies).

Primitiva (comando)	O que você vê	Referência
Logs (logs <fonte>; diagnose logs para agregado entre fontes)	Fluxo temporal de eventos de 5 fontes do backend (insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs)	references/logs.md
Métricas (diagnose metrics)	Séries temporais da instância EC2 (CPU / memória / disco / rede) em 1h / 6h / 24h / 7d	references/metrics.md
Integridade do BD (diagnose db)	Estado atual do Postgres via 7 verificações nomeadas (connections / slow-queries / bloat / size / index-usage / locks / cache-hit)	references/db-health.md
Conselheiro (diagnose advisor --json)	Problemas de varredura estática em 3 categorias (security / performance / health) com ruleId / affectedObject / recommendation	references/advisor.md
Políticas (db policies)	Regras RLS ativas de pg_policies (USING / WITH CHECK por comando por papel) — retorna todas as políticas como um dump	references/policies.md
Metadados (metadata --json)	Despejo de estado declarativo do backend (configuração de auth / tabelas / buckets / funções / modelos de IA / canais em tempo real)	references/metadata.md
Objetos de erro (nenhum comando — leia a resposta do SDK / HTTP)	Envelope de erro do SDK + status HTTP — a tabela de roteamento de um erro visível ao cliente para a fonte de log correta	references/error-objects.md
Estado de implantação (deployments list + deployments status <id> --json + logs function-deploy.logs)	Histórico de implantações do frontend (Vercel) + metadados por implantação, além de logs de implantação de edge functions	references/deploy-state.md
Assistência de IA (diagnose --ai "<descrição>")	Agente LLM que combina as outras primitivas — retorna um diagnóstico com sugestões	references/ai-assisted.md

Receitas de Sintomas

Cada receita é uma sequência de chamadas de primitivas com uma linha "procure por X" em cada etapa. A sintaxe dos comandos, flags e interpretação aprofundada estão nas referências por primitiva acima.

Receita: SDK retornou { data: null, error: { code, message } }

1. error-objects — leia code/message/details. Se o código começar com PGRST*, roteie pelo prefixo usando a tabela na referência.
2. logs (fonte correspondente por roteamento de error-objects) — encontre o timestamp do erro, obtenha o contexto completo do backend.
3. db-health (connections, locks, slow-queries) — apenas se o erro sugerir problema no BD (timeout do PostgREST, conflito de lock).

Receita: Resposta HTTP 4xx/5xx em uma requisição específica

1. error-objects — use a tabela de roteamento de status HTTP para escolher a fonte de log (cada status tem um caminho distinto; 429 é especial).
2. logs (fonte correta para aquele status) — encontre a linha da requisição com falha e o erro.
3. métricas — apenas para padrões 5xx que abrangem vários endpoints, para confirmar problema de carga em todo o sistema.

Receita: Problema de acesso RLS (403 em escrita, ou resultado vazio em leitura)

Mesmo bug, duas manifestações. Escritas (INSERT / UPDATE / DELETE) falham ruidosamente com 403. Leituras (SELECT) falham silenciosamente com uma array vazia — o PostgREST filtra as linhas negadas em vez de retornar 403, então a requisição parece bem-sucedida com zero linhas. O caminho de diagnóstico é o mesmo, exceto que o passo 1 se aplica apenas à variante 403.

1. logs (postgREST.logs) — apenas variante 403: encontre o evento de violação de política com contexto de tabela e papel. Variante de resultado vazio: pule — nenhum erro é registrado para linhas filtradas silenciosamente.
2. policies — liste as políticas para aquela tabela; percorra USING / WITH CHECK em relação à requisição real e ao claim JWT usado.
3. metadata — verifique a configuração de auth (qual claim alimenta auth.uid() / requesting_user_id(); para auth de terceiros como Clerk/Auth0, o provedor está registrado como um emissor JWT?).
4. consulta ao BD (db query "<sql>") — apenas variante de resultado vazio: confirme que linhas que deveriam estar visíveis realmente existem consultando como papel de serviço (não como o usuário): npx -y @insforge/cli db query "SELECT id, user_id FROM <tabela>". Distingue "RLS filtrou tudo" de "não existem dados correspondentes".

Receita: Falha no login / erros de callback OAuth / token expirado

1. logs (insforge.logs) — encontre erros de auth com timestamp e contexto do provedor.
2. metadata — verifique se o provedor está habilitado, se as URLs de redirecionamento correspondem exatamente à URL de callback (protocolo + host + caminho).

Receita: Erro de runtime / timeout de edge function

1. logs (function.logs) — obtenha o stack do erro e o contexto de execução.
2. metadata — confirme que a função existe e status: "active".
3. (Se necessário) npx -y @insforge/cli functions code <slug> — inspecione o código fonte para problemas óbvios.

Receita: Falha em functions deploy

1. deploy-state (function-deploy.logs) — encontre o erro de build/push.
2. metadata — confirme se a função acabou na lista de ativas (detecção de implantação parcial).

Receita: Falha em deployments deploy (Vercel)

1. deploy-state (deployments list + status <id> --json) — leia status, metadata.webhookEventType e envVarKeys.
2. Local npm run build — reproduza o mesmo erro localmente para iteração mais rápida.

Receita: Consulta lenta única / um endpoint lento

1. logs (postgres.logs) — encontre o texto da consulta e o timestamp.
2. db-health (slow-queries, index-usage) — slow-queries só captura enquanto ainda está em execução (>5s snapshot); verifique index-usage para um índice ausente. Já terminou? advisor (--category performance --json) tem o texto pg_stat_statements + tempo médio; o passo 1 tem o timestamp.
3. policies — se for uma tabela com proteção RLS, verifique se a política não está adicionando joins ocultos.

Receita: "A memória está em ~80% mas nada está lento"

1. Esperado — diga isso primeiro. Uma instância Postgres dedicada transforma RAM ociosa em buffers compartilhados e cache de página; memória alta constante com pouco tráfego é seu estado saudável, não um vazamento (references/metrics.md, "Memory: high is normal").
2. métricas (--range 24h) — apenas uma tendência crescente ou mortes/restarts por OOM mudam a resposta. Evidências de OOM vivem em postgres.logs como consequência da recuperação de crash ("terminating connection because of crash of another server process" / "automatic recovery in progress").
3. Com evidência de OOM, a correção é margem: faça upgrade para um plano pago e escolha um tamanho de instância maior (dashboard → Project Settings → Compute & Disk). OOM nas menores instâncias sob carga real é comum e esperado — nunca "reinicie para liberar memória".

Receita: Todas as respostas lentas / CPU/memória alta (incidente ativo)

1. métricas (--range 1h) — confirme pressão em todo o sistema (CPU / memória / disco).
2. db-health — o BD é o gargalo mais comum; verifique connections, locks, slow-queries.
3. logs (diagnose logs agregado) — padrões de erro entre fontes no timestamp do pico.
4. advisor (--severity critical) — problemas conhecidos pré-existentes que podem explicar a degradação.

Receita: Canal em tempo real não conecta / mensagens faltando

1. logs (insforge.logs) — erros WebSocket e falhas de assinatura.
2. metadata — verifique se o padrão do canal corresponde ao que o cliente assina, enabled: true.
3. policies — RLS na tabela subjacente (realtime entrega mudanças de linha; RLS determina quais linhas o assinante vê).

Receita: Limite de taxa 429

1. error-objects — confirme o status 429. Nenhum log é registrado para 429s; nenhum cabeçalho Retry-After é retornado. Não perca tempo procurando em logs.
2. métricas (--range 1h) — contexto geral de carga do backend.
3. A correção é sempre do lado do cliente: debounce, lote, backoff exponencial, elimine loops de repetição.

Receita: Timeout de gateway (502 / 503 / 504) em uma URL específica

Roteie pelo subsistema da URL antes de aprofundar:

Padrão de URL	Aprofunde em
/api/database/records/...	logs (postgREST.logs → postgres.logs) + db-health (locks, slow-queries)
/functions/<slug>	logs (function.logs) — a função pode estar em crash-loop
/api/auth/...	logs (insforge.logs)
Qualquer caminho durante pico em todo o sistema	métricas (--range 1h)

504s em caminhos não relacionados em uma instância pequena: suspeite de OOM primeiro. Timeouts de gateway intermitentes atingindo banco de dados, auth e funções ao mesmo tempo são a assinatura clássica de falta de memória nas menores instâncias: o kernel mata o Postgres, toda requisição em andamento expira no gateway enquanto a recuperação de crash é executada, e o ciclo se repete no próximo pico de carga.

Caminho rápido: npx -y @insforge/cli diagnose incident (Login na Plataforma necessário). O relatório é construído inteiramente no lado da nuvem — histórico de scrape do Prometheus, registros da plataforma, uma sonda de banco de dados de saída — então funciona mesmo enquanto a instância está parada ou travada, exatamente quando diagnose logs para de responder. Ele retorna um veredito (oom_likely, platform_operation_in_progress, paused_or_suspended, metrics_stopped, down_unknown, no_incident_detected) com a evidência e a ação recomendada; oom_likely já significa que as verificações de correlação de restart/memória abaixo passaram no lado da plataforma.

Se o comando estiver indisponível (CLI/backend mais antigo, modo de link --api-key), confirme manualmente em logs (postgres.logs) pela consequência da recuperação de crash — "terminating connection because of crash of another server process" / "automatic recovery in progress" — correlacionada temporalmente com o pico de 5xx: apenas evidência de recuperação prova um restart sujo do Postgres, então os timestamps devem coincidir antes que OOM se torne o diagnóstico principal (references/metrics.md). Com essa evidência, a correção é margem, não um loop de repetição:

1. Faça upgrade da instância — npx -y @insforge/cli projects upgrade-instance <tipo> (nano → micro → small → medium → large → xl), ou dashboard → Project Settings → Compute & Disk. No plano gratuito, faça upgrade para um plano pago primeiro, depois escolha o tamanho. O redimensionamento altera a fatura e a CLI pede confirmação interativa — obtenha a aprovação do usuário primeiro, depois execute sem supervisão com a flag --yes da CLI (o -y em npx -y é a flag de instalação do npm, não a de pular confirmação). O redimensionamento é assíncrono — consulte projects get até que operation_status seja limpo antes de declarar o incidente resolvido.
2. O redimensionamento reinicia o projeto como parte da mudança, o que também limpa qualquer estado travado — não há um restart separado voltado ao usuário, e um restart simples só compraria minutos antes que o próximo pico cause OOM novamente. OOM sob carga real nos menores tamanhos é comum e esperado, não um bug.

Receita: Pré-lançamento / auditoria proativa

Requer login na Plataforma (npx -y @insforge/cli login). Não disponível quando o projeto está vinculado via --api-key — use db-health + policies + metadata para uma auditoria manual nesse caso.

1. advisor — varredura completa, depois --severity critical primeiro, depois avisos.
2. advisor (--category security) — foque em problemas de segurança; verifique cruzadamente com policies (cobertura RLS) e metadata (configuração de auth, buckets públicos, presença de segredos).
3. advisor (--category performance) — verifique cruzadamente com db-health (slow-queries, index-usage, bloat).
4. advisor (--category health) — verifique cruzadamente com métricas (tendências de recursos em 7d).
5. Após correções, execute novamente advisor e confirme isResolved: true para cada ruleId tratado.

Receita: Não sabe por onde começar

1. ai-assisted (diagnose --ai "<erro ou URL>") — obtenha uma hipótese inicial.
2. Verifique reexaminando as primitivas que o diagnóstico nomeia. Confie nas observações das primitivas em vez da sugestão.

Quando a Causa Raiz é o Próprio InsForge

Alguns diagnósticos terminam em um defeito do lado do InsForge, não em uma configuração incorreta do projeto: um bug ou regressão da plataforma, uma chamada do SDK que se comporta mal, documentação ou uma habilidade que contradiz o comportamento observado, ou uma capacidade ausente. Uma sessão de depuração é exatamente onde estes são confirmados — reporte-os enquanto a evidência está em mãos:

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<resumo de uma linha>" \
  --detail "<o que aconteceu vs esperado, repro mínimo>" \
  --command "<a chamada com falha>" \
  --error "<erro literal dos logs>" \

…

[truncado para tradução]