InsForge Debug

Que fait InsForge Debug ?

Diagnostiquer les problèmes dans les projets InsForge en combinant les primitives d'observabilité du backend — logs, métriques, état de la base de données (db-health), conseiller (advisor), politiques, métadonnées, objets d'erreur, état de déploiement et assistance IA. Cette compétence fournit :

1. Une référence par primitive de débogage (une surface d'observabilité chacune — sous references/)
2. Des recettes de symptômes (ci-dessous) qui nomment la séquence de primitives pour les symptômes réactifs connus et les audits proactifs

Utilisez toujours npx -y @insforge/cli — n'installez jamais le CLI globalement.

Chemin le Plus Rapide : Triage Assisté par IA

Lorsque l'utilisateur fournit une description concrète (message d'erreur, URL défaillante, statut HTTP), transmettez-la à l'agent de débogage InsForge. Contrairement aux autres primitives, celui-ci retourne des suggestions, pas seulement des observations — vérifiez le diagnostic par rapport aux primitives qu'il cite avant d'agir.

npx -y @insforge/cli diagnose --ai "<description du problème>"

Voir references/ai-assisted.md pour savoir quand l'utiliser en premier vs quand l'ignorer, et comment vérifier la sortie.

Primitives de Débogage

Chaque primitive est une surface d'observabilité interrogeable indépendamment, soutenue par une source de données sous-jacente distincte. Les vrais diagnostics sont des compositions de primitives.

Toutes les commandes s'exécutent via npx -y @insforge/cli .... La (commande) affichée à côté de chaque primitive est la commande CLI réelle — les noms de primitives sont des étiquettes conceptuelles, pas des noms de sous-commandes CLI (par exemple, "DB health" est diagnose db, pas diagnose db-health ; "Policies" est db policies, pas diagnose policies).

Primitive (commande)	Ce que vous voyez	Référence
Logs (logs <source> ; diagnose logs pour l'agrégat inter-sources)	Flux temporel d'événements provenant de 5 sources backend (insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs)	references/logs.md
Métriques (diagnose metrics)	Séries temporelles de l'instance EC2 (CPU / mémoire / disque / réseau) sur 1h / 6h / 24h / 7d	references/metrics.md
État de la DB (diagnose db)	État actuel de Postgres via 7 vérifications nommées (connections / slow-queries / bloat / size / index-usage / locks / cache-hit)	references/db-health.md
Conseiller (diagnose advisor --json)	Problèmes détectés par analyse statique dans 3 catégories (security / performance / health) avec ruleId / affectedObject / recommendation	references/advisor.md
Politiques (db policies)	Règles RLS actives provenant de pg_policies (USING / WITH CHECK par commande par rôle) — renvoie toutes les politiques sous forme de dump	references/policies.md
Métadonnées (metadata --json)	Dump déclaratif de l'état du backend (configuration auth / tables / buckets / fonctions / modèles IA / canaux en temps réel)	references/metadata.md
Objets d'erreur (pas de commande — lisez l'enveloppe SDK / réponse HTTP)	Enveloppe d'erreur SDK + statut HTTP — la table de routage d'une erreur visible par le client vers la bonne source de log	references/error-objects.md
État de déploiement (deployments list + deployments status <id> --json + logs function-deploy.logs)	Historique des déploiements frontend (Vercel) + métadonnées par déploiement, plus les logs de déploiement des fonctions edge	references/deploy-state.md
Assistance IA (diagnose --ai "<description>")	Agent LLM qui combine les autres primitives — renvoie un diagnostic avec des suggestions	references/ai-assisted.md

Recettes de Symptômes

Chaque recette est une séquence d'appels de primitives avec une ligne "cherchez X" à chaque étape. La syntaxe des commandes, les indicateurs et l'interprétation approfondie se trouvent dans les références par primitive ci-dessus.

Recette : Le SDK a retourné { data: null, error: { code, message } }

1. error-objects — lisez code/message/details. Si le code commence par PGRST*, acheminez par préfixe en utilisant le tableau dans la référence.
2. logs (source correspondant au routage error-objects) — trouvez l'horodatage de l'erreur, obtenez le contexte côté backend complet.
3. db-health (connections, locks, slow-queries) — seulement si l'erreur suggère un problème de DB (timeout PostgREST, conflit de verrou).

Recette : Réponse HTTP 4xx/5xx sur une requête spécifique

1. error-objects — utilisez la table de routage du statut HTTP pour choisir la source de log (chaque statut a un chemin distinct ; 429 est spécial).
2. logs (bonne source pour ce statut) — trouvez la ligne de requête défaillante et l'erreur.
3. métriques — seulement pour les motifs 5xx couvrant plusieurs points d'accès, pour confirmer un problème de charge à l'échelle du système.

Recette : Problème d'accès RLS (403 en écriture, ou résultat vide en lecture)

Même bug, deux manifestations. Les écritures (INSERT / UPDATE / DELETE) échouent bruyamment avec un 403. Les lectures (SELECT) échouent silencieusement avec un tableau vide — PostgREST filtre les lignes refusées au lieu de retourner 403, donc la requête semble réussie avec zéro ligne. Le chemin de diagnostic est le même sauf que l'étape 1 ne s'applique qu'à la variante 403.

1. logs (postgREST.logs) — variante 403 uniquement : trouvez l'événement de violation de politique avec le contexte de la table et du rôle. Variante résultat vide : ignorez — aucune erreur n'est enregistrée pour les lignes filtrées silencieusement.
2. politiques — listez les politiques pour cette table ; parcourez USING / WITH CHECK par rapport à la requête réelle et à la revendication JWT utilisée.
3. métadonnées — vérifiez la configuration auth (quelle revendication alimente auth.uid() / requesting_user_id() ; pour l'auth tierce comme Clerk/Auth0, le fournisseur est-il enregistré comme émetteur JWT ?).
4. requête DB (db query "<sql>") — variante résultat vide uniquement : confirmez que les lignes qui devraient être visibles existent réellement en interrogeant en tant que rôle de service (pas en tant qu'utilisateur) : npx -y @insforge/cli db query "SELECT id, user_id FROM <table>". Distingue "RLS a tout filtré" de "aucune donnée correspondante n'existe".

Recette : Échec de connexion / Erreurs de callback OAuth / Jeton expiré

1. logs (insforge.logs) — trouvez les erreurs d'auth avec l'horodatage et le contexte du fournisseur.
2. métadonnées — vérifiez que le fournisseur est activé, que les URL de redirection correspondent exactement à l'URL de callback (protocole + hôte + chemin).

Recette : Erreur d'exécution / dépassement de délai de la fonction edge

1. logs (function.logs) — obtenez la pile d'erreurs et le contexte d'exécution.
2. métadonnées — confirmez que la fonction existe et que status: "active".
3. (Si nécessaire) npx -y @insforge/cli functions code <slug> — inspectez le source pour des problèmes évidents.

Recette : functions deploy a échoué

1. deploy-state (function-deploy.logs) — trouvez l'erreur de build/push.
2. métadonnées — confirmez si la fonction s'est retrouvée dans la liste active (détection de déploiement partiel).

Recette : deployments deploy a échoué (Vercel)

1. deploy-state (deployments list + status <id> --json) — lisez status, metadata.webhookEventType et envVarKeys.
2. Local npm run build — reproduisez la même erreur localement pour une itération plus rapide.

Recette : Une seule requête lente / un point d'accès lent

1. logs (postgres.logs) — trouvez le texte de la requête et l'horodatage.
2. db-health (slow-queries, index-usage) — slow-queries ne l'attrape que si elle est encore en cours (>5 s snapshot) ; vérifiez index-usage pour un index manquant. Déjà terminée ? conseiller (--category performance --json) a le texte pg_stat_statements + le temps moyen ; l'étape 1 a l'horodatage.
3. politiques — s'il s'agit d'une table verrouillée par RLS, vérifiez que la politique n'ajoute pas de jointures cachées.

Recette : "La mémoire est à ~80% mais rien n'est lent"

1. Attendu — dites-le d'abord. Une instance Postgres dédiée transforme la RAM inutilisée en tampons partagés et en cache de pages ; une mémoire élevée stable avec peu de trafic est son état sain, pas une fuite (references/metrics.md, "Mémoire : élevé est normal").
2. métriques (--range 24h) — seule une tendance à la hausse ou des kills/redémarrages OOM changent la réponse. Les preuves OOM se trouvent dans postgres.logs comme les séquelles de crash-redémarrage ("terminating connection because of crash of another server process" / "automatic recovery in progress").
3. Avec des preuves OOM, la solution est de la marge : passer à un plan payant et choisir une taille d'instance plus grande (tableau de bord → Project Settings → Compute & Disk). L'OOM sur les plus petites instances sous charge réelle est courant et attendu — ne "redémarrez jamais pour libérer de la mémoire".

Recette : Toutes les réponses lentes / CPU/mémoire élevé (incident actif)

1. métriques (--range 1h) — confirmez la pression à l'échelle du système (CPU / mémoire / disque).
2. db-health — la DB est le goulot d'étranglement le plus courant ; vérifiez connections, locks, slow-queries.
3. logs (diagnose logs agrégat) — motifs d'erreur sur toutes les sources à l'horodatage du pic.
4. conseiller (--severity critical) — problèmes connus préexistants qui peuvent expliquer la dégradation.

Recette : Le canal en temps réel ne se connecte pas / messages manquants

1. logs (insforge.logs) — erreurs WebSocket et échecs d'abonnement.
2. métadonnées — vérifiez que le motif du canal correspond à ce à quoi le client s'abonne, enabled: true.
3. politiques — RLS sur la table sous-jacente (le temps réel délivre les modifications de lignes ; RLS contrôle quelles lignes l'abonné voit).

Recette : Limite de taux 429

1. error-objects — confirmez le statut 429. Aucun log n'est enregistré pour les 429 ; aucun en-tête Retry-After n'est renvoyé. Ne perdez pas de temps à chercher dans les logs.
2. métriques (--range 1h) — contexte global de charge du backend.
3. La correction est toujours côté client : débouncez, regroupez, backoff exponentiel, éliminez les boucles de réessai.

Recette : Délai d'attente de la passerelle (502 / 503 / 504) sur une URL spécifique

Acheminez par sous-système d'URL avant de creuser :

Motif d'URL	Creuser dans
/api/database/records/...	logs (postgREST.logs → postgres.logs) + db-health (locks, slow-queries)
/functions/<slug>	logs (function.logs) — la fonction peut être en boucle de crash
/api/auth/...	logs (insforge.logs)
Tout chemin lors d'un pic à l'échelle du système	métriques (--range 1h)

Les 504 sur des chemins non apparentés sur une petite instance : suspectez OOM d'abord. Les délais d'attente intermittents de la passerelle frappant la base de données, l'auth et les fonctions simultanément sont la signature classique du manque de mémoire sur les plus petites tailles d'instance : le noyau tue Postgres, chaque requête en cours expire au niveau de la passerelle pendant que la récupération après crash s'exécute, et cela se répète au prochain pic de charge.

Chemin rapide : npx -y @insforge/cli diagnose incident (Connexion à la plateforme requise). Le rapport est entièrement construit côté cloud — historique de scraping Prometheus, enregistrements de la plateforme, une sonde de base de données sortante — donc il fonctionne même lorsque l'instance est arrêtée ou bloquée, exactement quand diagnose logs cesse de répondre. Il renvoie un verdict (oom_likely, platform_operation_in_progress, paused_or_suspended, metrics_stopped, down_unknown, no_incident_detected) avec les preuves et l'action recommandée ; oom_likely signifie déjà que les vérifications de corrélation redémarrage/mémoire ci-dessous ont été effectuées côté plateforme.

Si la commande est indisponible (CLI/backend plus ancien, mode de lien --api-key), confirmez manuellement dans logs (postgres.logs) via les séquelles de crash-redémarrage — "terminating connection because of crash of another server process" / "automatic recovery in progress" — corrélé dans le temps avec le burst 5xx : la preuve de récupération seule ne prouve qu'un redémarrage non propre de Postgres, donc les horodatages doivent correspondre avant que OOM ne devienne le diagnostic principal (references/metrics.md). Avec cette preuve, la solution est de la marge, pas une boucle de réessai :

1. Mettez à niveau l'instance — npx -y @insforge/cli projects upgrade-instance <type> (nano → micro → small → medium → large → xl), ou tableau de bord → Project Settings → Compute & Disk. Sur le plan gratuit, passez d'abord à un plan payant, puis choisissez la taille. Le redimensionnement modifie la facture et le CLI demande une confirmation interactive — obtenez d'abord l'accord de l'utilisateur, puis exécutez sans surveillance avec le --yes au niveau CLI (le -y dans npx -y est l'indicateur d'installation de npm, pas celui de saut de confirmation). Le redimensionnement est asynchrone — interrogez projects get jusqu'à ce que operation_status soit effacé avant de déclarer l'incident résolu.
2. Le redimensionnement redémarre le projet dans le cadre du changement, ce qui efface également tout état bloqué — il n'y a pas de redémarrage séparé visible par l'utilisateur, et un simple redémarrage ne ferait que gagner quelques minutes avant que le prochain pic ne provoque à nouveau un OOM. L'OOM sous charge réelle sur les plus petites tailles est courant et attendu, pas un bug.

Recette : Audit pré-lancement / proactif

Nécessite une connexion à la plateforme (npx -y @insforge/cli login). Non disponible lorsque le projet est lié via --api-key — utilisez db-health + politiques + métadonnées pour un audit manuel dans ce cas.

1. conseiller — analyse complète, puis --severity critical d'abord, puis les avertissements.
2. conseiller (--category security) — concentrez-vous sur les problèmes de sécurité ; recoupez avec politiques (couverture RLS) et métadonnées (configuration auth, buckets publics, présence de secrets).
3. conseiller (--category performance) — recoupez avec db-health (slow-queries, index-usage, bloat).
4. conseiller (--category health) — recoupez avec métriques (tendances des ressources sur 7d).
5. Après les corrections, réexécutez conseiller et confirmez isResolved: true pour chaque ruleId traité.

Recette : Je ne sais pas par où commencer

1. ai-assisted (diagnose --ai "<erreur ou URL>") — obtenez une hypothèse de départ.
2. Vérifiez en revérifiant les primitives que le diagnostic nomme. Faites confiance aux observations des primitives plutôt qu'à la suggestion.

Lorsque la Cause Racine Est InsForge Lui-Même

Certains diagnostics aboutissent à un défaut côté InsForge, pas à une mauvaise configuration du projet : un bug ou une régression de la plateforme, un appel SDK qui se comporte mal, de la documentation ou une compétence qui contredit le comportement observé, ou une fonctionnalité manquante. Une session de débogage est exactement l'endroit où ceux-ci sont confirmés — signalez-les pendant que les preuves sont en main :

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<résumé d'une ligne>" \
  --detail "<ce qui s'est passé vs attendu, repro minimal>" \
  --command "<l'appel défaillant>" \
  --error "<erreur textuelle des logs>"