Éditeurs, assistants et autres frontends
Aggrega s’utilise depuis plus d’un endroit : un terminal, l’extension Visual Studio Code, un assistant IA connecté via le Model Context Protocol (MCP), et tout programme qui pilote le binaire aggrega. Aucun de ces frontends n’embarque son propre compilateur. Chacun exécute le binaire aggrega, ou en joint un déjà en cours d’exécution, et l’interroge ; ainsi l’analyse du YAML, la résolution du catalogue et la construction du graphe se font en un seul endroit, et ce qu’un frontend affiche est ce que ce binaire a compilé. Un frontend n’en réimplémente rien, si bien qu’il n’existe pas de seconde copie susceptible de diverger de la première.
Ce chapitre décrit le contrat que partagent ces frontends, et ce que chacun demande au binaire.
Le graphe IR est le contrat public
Compiler une Release, avec l’Aggregate et le Manifest qu’elle nomme, produit un graphe de représentation intermédiaire (IR) : chaque nœud, avec le composant qu’il instancie, la version vers laquelle ce composant a été résolu, la frontière et le sous-système où il se trouve et le fichier qui l’a déclaré ; chaque connexion entre nœuds ; les Features rattachées à chacun ; et les valeurs mises en correspondance sur eux, avec la provenance de chacune. C’est l’instantané de ce que le compilateur s’apprête à rendre en artefacts.
La forme du graphe est publiée sous forme de JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, et la référence du schéma IR décrit chaque champ. Un frontend lit le graphe d’après ce schéma, et non d’après les mécanismes internes du compilateur ; le schéma est donc le seul endroit où la forme évolue, et un frontend écrit dans n’importe quel langage la suit de la même manière.
Les valeurs qu’un auteur a déclarées sensibles sont retenues hors du graphe partout où celui-ci est remis. Un frontend qui en a besoin en clair les demande explicitement, et tout ce que la réponse atteint ensuite les porte en clair.
Trois façons de demander le graphe
Le même graphe est disponible sur chaque surface, et chaque réponse est un document de graphe complet :
- Depuis la ligne de commande.
aggrega build,aggrega inspectappliquée à une Release etaggrega validate --releaseacceptent chacune--ir-graph, qui écrit sur la sortie standard, en JSON, le graphe calculé par cette exécution, en plus de tout ce que la commande produit déjà.--unredactedà côté affiche les valeurs sensibles. Voiraggrega inspect. - Depuis le démon. Une requête
aggrega/irGraphadressée àaggrega serve, qui nomme la Release par son chemin relatif à la racine de l’espace de travail, reçoit en réponse le même document sousgraph;unredacted: truedemande les valeurs sensibles. Voiraggrega serve. - Depuis un assistant IA. Les outils
cli-inspect,cli-buildetcli-validatedu serveur MCP prennent l’option de la commande comme argumentir_graph. Voiraggrega mcp.
Chaque réponse décrit la Release telle qu’elle était au moment où la question a été posée. Un frontend qui suit les modifications redemande : l’extension Visual Studio Code redessine son graphe chaque fois qu’un document est enregistré.
L’extension Visual Studio Code
L’extension Aggrega pour Visual Studio Code démarre aggrega serve et le maintient en exécution pour l’espace de travail. Chaque réponse qu’elle affiche provient du binaire aggrega : la plupart de ce démon — parmi lesquelles les diagnostics pendant l’édition, le survol, la complétion, l’accès à la définition, la recherche de références, le build et l’aperçu du build — et le reste de l’exécution des propres commandes du binaire.
Son graphe de topologie est le graphe IR. L’extension envoie aggrega/irGraph pour la Release sélectionnée et dessine la réponse : les frontières et les sous-systèmes comme des conteneurs imbriqués, les composants comme des nœuds, les connexions comme des arêtes et, sur un nœud ou une connexion sélectionnés, les Features qui y sont rattachées. Le compilateur envoie la topologie et jamais de coordonnées ; la disposition est calculée dans l’éditeur. Rattacher une Feature depuis le graphe passe aussi par le démon : le compilateur nomme le document et l’endroit où le rattachement doit figurer, et l’extension l’y écrit. Voir le graphe de topologie pour ce que la vue affiche et fait.
Le serveur MCP
aggrega mcp exécute le binaire comme serveur Model Context Protocol, si bien qu’un assistant IA découvre les opérations d’Aggrega et les appelle au lieu de lire la sortie des commandes. Sur l’entrée et la sortie standard, il parle JSON-RPC 2.0 délimité par des sauts de ligne, ce qui permet à un client qui le lance comme sous-processus de le joindre ; sur HTTP, il sert un unique point de terminaison, /mcp, pour les appelants situés sur d’autres machines. Ses outils sont les opérations du compilateur — lire des schémas, décrire l’espace de travail, valider, construire, rédiger et modifier des documents — et chaque appel reçoit sa réponse du même binaire que celui qu’exécute la ligne de commande.
Connecter le serveur MCP explique comment connecter chaque client, et Ce que votre assistant peut faire avec Aggrega présente ce qu’offrent les outils.
Le démon aggrega serve
aggrega serve exécute le compilateur comme processus de longue durée pour les éditeurs. Il conserve d’une requête à l’autre les documents analysés, le catalogue résolu et les diagnostics, si bien qu’un éditeur pose de nombreuses petites questions sans payer à chaque fois un chargement complet du catalogue.
Le protocole est JSON-RPC 2.0 sur l’entrée et la sortie standard, chaque message étant précédé d’un en-tête Content-Length, avec des méthodes sous l’espace de noms aggrega/. Ce n’est pas le Language Server Protocol, car il transporte des opérations pour lesquelles ce protocole n’a pas de place, comme la requête du graphe IR ; une extension d’éditeur traduit entre les requêtes de son éditeur et ces méthodes, et réutilise les formes de position, de plage et d’emplacement de ce protocole là où elles conviennent. Une session s’ouvre avec aggrega/initialize, qui indique l’espace de travail et la version du binaire qui répond ; le démon pousse les diagnostics avec aggrega/publishDiagnostics ; et la notification aggrega/shutdown la termine proprement.
Chaque corps de message est publié sous forme de schéma, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, décrit dans la référence du format des messages ; l’extension Visual Studio Code en tire ses types de messages. Un autre éditeur s’intègre en parlant le même protocole. La référence de aggrega serve décrit chaque méthode, ce qu’elle lit et écrit, et les erreurs qu’elle lève.