Aller au contenu principal
Version: 1.0.0

Dépannage

Ce guide part des symptômes courants. Pour les codes détaillés, lire la référence diagnostics.

zsh: command not found: code​

La commande terminal de VS Code n’est pas dans le PATH. Sur macOS, activez-la depuis la palette de commandes, puis ouvrez un nouveau terminal. code et la CLI touba sont deux commandes distinctes ; réinstaller Touba ne configure pas code.

Pour installer l’extension sans terminal, recherchez @id:touba.touba-tools dans la vue Extensions de VS Code, puis cliquez sur Installer.

zsh: command not found: touba​

Cause probable :

  • l’extension VS Code Touba est installée, mais la CLI Touba n’est pas disponible dans le PATH du terminal.

À retenir :

  • le VSIX installe l’extension Touba Language Toolkit ;
  • il ne crée pas automatiquement les commandes terminal touba, touba run, touba compile, touba inspect, touba manifest ou touba handler stub ;
  • installer la CLI depuis Installation, puis ouvrir un nouveau terminal ;
  • pour un fichier .tb simple, utiliser la commande VS Code Touba: Run Current File ;
  • pour touba init, touba prepare ou les commandes runtime, utiliser un environnement où la CLI Touba est explicitement disponible.

Le runtime refuse un tool avant handler​

Causes probables :

  • manifest absent ;
  • binding absent ;
  • grant manquant ;
  • secret non résolu ;
  • payload invalide.

Actions :

Terminal
touba inspect program.air.json --manifest touba.manifest.json
touba run program.air.json --manifest touba.manifest.json --inputs-json '{"request":{}}'

Lire failure_detected dans la trace ou l’erreur CLI.

touba prepare --mode check échoue​

Causes probables :

  • module source hors convention ;
  • manifest manquant alors qu’un tool existe ;
  • binding absent ;
  • stub handler absent ;
  • grant, secret ou accès mémoire attendu absent ;
  • binding resté dans le manifest alors que le tool n’existe plus.

Actions :

Terminal
touba prepare --mode plan
touba prepare --mode write
touba prepare --mode check

Relire les diagnostics avant d’ajouter un grant ou un secret. prepare ne doit pas élargir les droits silencieusement.

PreparedAirDrift signale un AIR absent ou différent de la préparation attendue. Après une écriture inchangée, check ne réclame plus de réécriture de cet AIR. HandlerDeclaredContractDrift signale un contrat de stub devenu obsolète (grants, secrets, arguments ou retour). Mettez le handler à jour explicitement : write préserve votre code. Le test de contrat généré vérifie l'admission et les refus structurels ; ajoutez un test positif de votre logique métier.

Le handler ne reçoit pas un secret​

Vérifier :

  • le tool déclare secrets HANDLE ;
  • le binding contient "secrets": ["HANDLE"] ;
  • le binding contient le grant attendu ;
  • le fichier secrets est fourni à l’exécution ;
  • la variable d’environnement existe ;
  • si un agent est actif, le scope agent autorise ce handle.

ask reste en pause​

Touba ne lit pas stdin.

Fournir l’entrée explicitement :

Terminal
touba run program.air.json --user-inputs user-inputs.json

Pour un essai manuel, utiliser le mode hôte interactif :

Terminal
touba run program.air.json --interactive-user-inputs

La référence d’interaction est visible dans la trace de pause.

Un test live échoue​

Un live dépend du réseau, du service externe, des quotas et parfois d’une clé API.

Commencez par un dry-run quand il existe, puis passez au live seulement pour valider l’intégration réelle.

Les traces semblent manquer une valeur​

C’est parfois attendu.

Les traces ne doivent pas contenir :

  • valeurs de secrets ;
  • réponses exactes de ask dans user_interaction_answered ;
  • payloads sensibles refusés.

Elles doivent contenir les références, handles, modes et raisons de refus nécessaires à l’audit.