Touba Language Toolkit pour VS Code

Touba Language Toolkit est l’extension officielle VS Code pour les fichiers .tb. Elle relie l’édition quotidienne au compilateur, à la CLI et aux artefacts Touba.

Disponibilité

La mise à jour décrite ici est en cours de qualification sur les quatre plateformes. Les instructions d’installation ci-dessous s’appliqueront à sa publication. Pour explorer un projet dès maintenant, utilisez touba explore avec la CLI Touba.

Explorer le projet

Touba: Explore Project ouvre un graphe interactif avec les vues Architecture, Parcours et Gouvernance. Recherchez et filtrez les ressources, consultez leurs signatures et responsabilités, puis ouvrez leur source. Touba: View in Graph sélectionne la déclaration sous le curseur. Le graphe suit les sauvegardes ; son utilisation requiert un espace de travail approuvé.

Le navigateur propose les mêmes vues avec touba explore. Guide de l’explorateur · Tutoriel guidé.

Installer l’extension

Dans VS Code 1.143.1 ou ultérieur, recherchez Touba Language Toolkit par Touba dans Extensions, puis cliquez sur Installer. La recherche @id:touba.touba-tools permet de retrouver directement l’extension. Cette méthode ne nécessite aucune commande terminal.

Si la commande code est disponible, vous pouvez aussi utiliser le terminal :

Terminal

code --install-extension touba.touba-tools

VS Code sélectionne automatiquement le paquet adapté : macOS Apple Silicon, macOS Intel, Linux x64 ou Windows x64. Pour une installation hors ligne, téléchargez le VSIX de votre plateforme dans le Hub, puis choisissez Extensions → … → Install from VSIX….

L’extension embarque le compilateur et le runtime pour l’édition et les fichiers autonomes. Installez la CLI Touba pour les commandes terminal et les parcours de projet.

macOS : commande code introuvable

Si le terminal affiche zsh: command not found: code, la commande de VS Code n’est pas dans le PATH. code appartient à VS Code ; touba est la CLI du langage. Il suffit de configurer VS Code :

1. Ouvrez Visual Studio Code depuis Applications.
2. Ouvrez la palette de commandes avec ⌘⇧P (Cmd+Shift+P).
3. Recherchez shell command, puis choisissez Shell Command: Install 'code' command in PATH.
4. Ouvrez un nouveau terminal, puis vérifiez et installez l’extension :

Terminal

code --version
code --install-extension touba.touba-tools

Pour une installation ponctuelle sans modifier le PATH, si VS Code se trouve dans /Applications, utilisez son chemin complet :

Terminal

"/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" --install-extension touba.touba-tools

Vous pouvez également utiliser la vue Extensions décrite plus haut. Voir la procédure officielle VS Code pour macOS.

Fonctions de l’éditeur

L’extension fournit :

• coloration et association des fichiers .tb ;
• diagnostics issus du compilateur ;
• symboles, complétion, hover et navigation vers les définitions ;
• exécution explicite du fichier courant ;
• inspection des artefacts AIR, manifest et rapports ;
• exploration graphique des ressources, des parcours et de la gouvernance ;
• rendu texte des traces et vues d’architecture ;
• navigation d’un événement de trace vers sa source.

Les diagnostics de capacité incluent les descriptions requises pour les catalogues présentés au provider de décision.

Commandes

Commande	Fonction
Touba: Explore Project	ouvrir l’explorateur graphique du projet
Touba: View in Graph	retrouver l’élément sous le curseur dans le graphe
Touba: Run Current File	compiler et exécuter le fichier .tb actif
Touba: Check CLI	vérifier la commande Touba résolue
Touba: Open Terminal	ouvrir un terminal pour le projet
Touba: Inspect Artifact	inspecter un AIR, manifest, trace ou rapport
Touba: Inspect Artifacts	inspecter un ensemble explicite d’artefacts
Touba: Render Architecture	rendre une projection AIR lisible
Touba: Render Trace	afficher une timeline de trace
Touba: Open Trace Event Source	ouvrir la source d’un événement
Touba: Validate Memory Action Plan	valider un plan d’action mémoire

Repérer les packages

Le dossier packages/ géré par Touba porte un repère P, une couleur dédiée et l’infobulle Touba packages, y compris dans un projet imbriqué. Pour afficher également une icône de boîte, choisissez Preferences: File Icon Theme → Touba File Icons dans la palette. Ce thème est facultatif ; votre thème actuel reste inchangé. Ses icônes de boîte suivent le nom du dossier, tandis que le repère P vérifie le manifeste Touba du parent.

Si le repère est masqué, activez explorer.decorations.badges et explorer.decorations.colors. Une décoration Git peut avoir priorité.

Résolution de la CLI

Pour Check CLI et les commandes terminal, l’extension cherche la CLI dans cet ordre :

1. TOUBA_CLI_PATH lorsqu’il est défini ;
2. touba dans le PATH du processus VS Code ;
3. $HOME/.touba/bin/touba.

Lancez Touba: Check CLI pour afficher la commande retenue et vérifier les versions de protocoles. Les fonctions d’édition peuvent utiliser le runtime embarqué ; les commandes terminal utilisent la CLI installée.

Exécuter un fichier

Touba: Run Current File compile le document actif vers un AIR temporaire, puis l’exécute avec le runtime embarqué, sauf si TOUBA_CLI_PATH choisit une autre installation. Les interactions ask ouvrent un champ VS Code et reprennent le run avec une entrée hôte explicite.

Le journal SQLite reste dans .touba/traces.sqlite après l'exécution. La sortie indique son chemin et la référence à ouvrir avec Touba: Render Trace. Les pages remplacent la vue précédente ; une longue trace reste consultable. Une interaction après un dispatch n'est pas rejouée automatiquement.

Un programme qui dépend de tools externes, de secrets ou d’un manifest utilise le parcours normal du projet. L’extension ne découvre pas un .env, un handler ou un secret par convention.

Lire les artefacts

Les commandes de rendu ouvrent des vues texte dérivées d’artefacts choisis par l’utilisateur. Une trace fournit la séquence d’événements ; une projection d’architecture fournit les déclarations, imports, budgets et relations. Cette lecture reste alignée sur l’AIR et ne crée pas de statut parallèle.

Pour un parcours complet, consultez le projet VS Code et JavaScript.

Lire une trace conservée

Pour conserver une trace et obtenir sa référence :

Terminal

touba run programme.air.json --trace-store .touba/traces.sqlite --output json-reference > run.json

1. Ouvrez run.json, puis lancez Touba: Render Trace.
2. Sélectionnez le journal traces.sqlite correspondant.
3. La sortie Touba Trace affiche une page. Next page la remplace par la suivante.

Chaque page contient au plus 100 événements et 1 Mio de contenu d’événements. La lecture utilise le Core embarqué, dans un espace de travail approuvé, et laisse le journal inchangé. Une référence identifie un segment d’exécution ; une reprise possède son propre segment.

Touba: Open Trace Event Source accepte également run.json ou une référence seule. Choisissez l’AIR exécuté, l’identifiant de l’événement et le journal. L’extension vérifie le segment, lit l’événement demandé et ouvre sa source. Les traces JSON complètes restent lisibles jusqu’à 16 Mio.

Premier essai

Enregistrez ce programme dans un fichier .tb, puis lancez Touba: Run Current File.

source.tb

module examples.test

strategy RunTest
    do
        show
            with message as "test"

Identifier une installation et résoudre un problème

Touba: Check CLI affiche la build chargée, la plateforme et la CLI retenue. Après une mise à jour du VSIX, sauvegardez vos fichiers puis utilisez Developer: Reload Window. Vérifiez séparément la CLI avec touba version.

Pour choisir une CLI, définissez TOUBA_CLI_PATH dans l’environnement qui lance VS Code, puis redémarrez l’application. Les paramètres terminal.integrated.env.* s’appliquent au terminal, pas à l’hôte de l’extension.

Un diagnostic CompilerUnavailable signale que le compilateur sélectionné ne démarre pas ou fournit une réponse inexploitable. Vérifiez sa sélection et TOUBA_COMPILE_BIN, puis rouvrez le fichier. Les diagnostics de syntaxe et de type sont actualisés pendant l’édition.

La navigation d’une trace utilise les chemins relatifs des sources, depuis le dossier ouvert. Sans dossier de travail, choisissez la racine demandée. Conservez la structure des sources avec les artefacts correspondants.