Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Vue d’ensemble de la CLI

La CLI aggrega est le point d’entrée du compilateur. Chaque interaction avec Aggrega — compiler un Aggregate en artefacts déployables, inspecter le catalogue ou l’IR, résoudre et épingler les dépendances, publier des entités de catalogue, vérifier la correction avec validate, vérifier les conventions de publication avec lint et servir un IDE — passe par une sous-commande de aggrega. Cet ensemble de chapitres couvre les flags, les entrées et les sorties de chaque sous-commande.

aggrega validate et aggrega lint sont des vérificateurs complémentaires dont les trois portées se reflètent mutuellement — le catalogue entier, la fermeture des dépendances d’une Release, ou une seule entité. aggrega validate vérifie la correction (schéma, piliers, résolution des références, extends, capacité du provider pour le type d’entrée et — pour une entité de rendu — un rendu isolé) ; aggrega lint vérifie les conventions de publication (nommage, alignement sur le répertoire de catégorie, préfixes d’annotation et ampleur de l’incrément de version). Aucun des deux n’émet d’artefacts ; utilisez validate pour répondre à « est-ce correct ? » et lint pour répondre à « cela suit-il la discipline de publication du catalogue ? ».

aggrega build suit le principe du point d’entrée unique : la Release est la seule entrée de compilation. aggrega build --release release.yaml lit les pointeurs aggregate: et manifest: de la Release pour localiser le reste de la topologie, et produit une sortie par frontière sous dist/ : une frontière nommée est produite sous son directory: déclaré, ou sous dist/boundaries/<boundary-name>/ lorsqu’elle n’en déclare aucun ; une Release qui déclare des components: de premier niveau au lieu de frontières nommées est produite à plat sous dist/. Chaque composant de la topologie doit appartenir à l’une de ces frontières, et un composant qu’aucune d’elles ne contient arrête le build : un composant rejoint une frontière soit en étant nommé sous les components: de cette frontière, sous l’id qu’il porte une fois les sous-Aggregates aplatis, soit en se trouvant dans un sous-Aggregate que la frontière achemine sous aggregates:. Un composant qui ne rejoint ni l’une ni l’autre serait produit en dehors de toute frontière déclarée par la Release, sans aucune source pour son emplacement de sortie, sa sync wave, ses annotations et son infra: par composant ; le build s’arrête donc et nomme le composant au lieu d’émettre des artefacts auxquels la configuration des frontières de la Release n’a jamais été appliquée. La même relation est vérifiée du côté de la Release : une entrée de frontière qui nomme un composant que la topologie ne contient pas ne configure rien ; elle arrête donc aussi le build, et le diagnostic indique l’id que l’entrée désignait. aggrega pull partage la forme avec la Release comme entrée ; aggrega inspect prend n’importe quelle entité — un nom de catalogue, un fichier d’entité, une référence de registre ou une Release ; aggrega push prend une entité de catalogue ; aggrega validate et aggrega lint acceptent une entité de catalogue, une Release (via --release) ou le catalogue entier ; aggrega serve s’exécute comme un processus de longue durée. La page des flags globaux documente les flags qui s’appliquent à toutes les sous-commandes.

Ce qu’une release peut changer dans les commandes, les options et les outils de l’assistant — et ce qu’une release de correctif ne change jamais — est indiqué dans Compatibilité.

Référence par commande

  • aggrega build — la commande de compilation principale. Lit un pointeur de Release, résout l’Aggregate et le Manifest qu’il référence, et émet des artefacts compilés par frontière.
  • aggrega inspect — une vue lisible de n’importe quelle entité : une entité de catalogue par son nom, un fichier d’entité par son chemin, une entité publiée lue directement depuis son registry, ou une Release entièrement résolue, dont --ir-graph écrit l’IR Graph en JSON et dont --closure rapporte la fermeture des dépendances.
  • aggrega pull — résout les dépendances d’une Release et écrit un lockfile par Release qui épingle chaque dépendance ; met en cache les entités de catalogue et les artefacts source.
  • aggrega push — publie une entité de catalogue dans un registry OCI, en la signant éventuellement au moment du push.
  • aggrega sign — signe un ou plusieurs artefacts déjà publiés et attache chaque signature en tant que referrer OCI.
  • aggrega auth token — obtient de manière interactive un jeton d’identité OIDC et l’affiche sur stdout, pour une seule authentification valable pour un lot de signatures keyless.
  • aggrega registry — gère les registries connus du workspace et leur politique de confiance des signatures : ajouter, lister et supprimer des entrées, et construire avec registry update un index local consultable des métadonnées de catalogue publiées.
  • aggrega search — recherche dans l’index local des registries configurés les entités de catalogue publiées et les plugins CLI installables, à partir d’une requête en texte libre et de filtres de facettes facultatifs.
  • aggrega validate — vérifie la correction (schéma, piliers, résolution des références, extends, capacité pour le type d’entrée, rendu isolé) sur le catalogue entier, la fermeture des dépendances d’une Release (--release) ou une seule entité.
  • aggrega lint — vérifie les conventions de publication sur le catalogue entier, la fermeture des dépendances d’une Release (--release) ou une seule entité ; --pre-publish ajoute le contrôle de l’incrément de version qui interroge le registry.
  • aggrega serve — un démon de longue durée exposant le compilateur comme service (JSON-RPC sur stdin/stdout) pour l’intégration aux IDE.
  • aggrega version — affiche la version de la CLI ; -o json émet un objet lisible par machine.
  • aggrega get-schema — affiche le JSON Schema canonique d’un type d’entité ou de contrat ; --list nomme chaque type. La forme de référence par rapport à laquelle écrire un fichier.
  • aggrega scaffold — affiche un document de départ pour un type d’entité, dérivé du schéma de ce type : les champs obligatoires, les champs fixes déjà renseignés et un espace réservé partout où une valeur est nécessaire. La rédaction n’écrit aucun fichier ; redirigez la sortie là où vous le souhaitez. Avec --example, la commande écrit à la place l’un des exemples exécutables de la documentation dans un nouveau répertoire, et --example --list les nomme.
  • aggrega mcp — exécute un serveur Model Context Protocol, sur l’entrée et la sortie standard ou sur HTTP, afin qu’un client compatible MCP devienne un assistant d’écriture qui connaît Aggrega. Voir Écrire des fichiers Aggrega.
  • aggrega skills — installe la skill qui apprend à un assistant IA à installer et utiliser Aggrega dans le dossier de skills de cet assistant, pour un projet ou, avec --global, pour tous vos projets.
  • aggrega cache — inspecte et entretient les caches sur disque : liste ce qu’ils contiennent, récupère les entrées du cache d’artefacts qu’aucun lockfile ne référence, réduit le cache des modules compilés à une taille maximale ou efface tous les caches.
  • aggrega config — inspecte et gère la configuration que lit Aggrega : montre ce qui s’applique et quelle couche a décidé chaque réglage, initialise une configuration fonctionnelle et fige dans le workspace les réglages critiques pour le build.
  • aggrega deprecate — attache un marqueur de dépréciation signé à un artefact déjà publié.
  • aggrega edit-document — applique une modification structurée et délimitée à un document, en préservant chaque octet qu’elle ne touche pas.
  • aggrega explain — explique la condition d’arrêt que nomme un code.
  • aggrega import — transforme une description de source étrangère en brouillons de fichiers de rédaction Aggrega.
  • aggrega login — s’authentifie auprès d’un registre OCI et stocke l’identifiant que présentent push, pull et lint --pre-publish.
  • aggrega logout — supprime un identifiant de registre stocké.
  • aggrega pin — enregistre les épinglages de contenu des entrées externes d’une entité dans l’entity.lock placé à côté.
  • aggrega plugin — liste les plugins Wasm que la CLI peut résoudre, ajoute ou supprime une liaison de workspace et vérifie un guest avant que vous le publiiez.
  • aggrega push-artifact — publie un artefact de données autonome, tel qu’un bundle de documentation, sur un registre OCI sous son espace de noms docs/.
  • Configuration — dans quel fichier placer un réglage, et comment les couches se combinent. Commencez ici : la page s’ouvre sur les deux fichiers dont la plupart des projets ont besoin et garde pour la suite les mécanismes auxquels recourt un projet plus important.
  • Flags globaux — flags partagés entre les sous-commandes (la racine du workspace, le fichier de configuration global, la sortie en couleur et la sortie simple accessible, et le mode hors ligne). Le mode hors ligne est aussi accessible comme réglage de configuration et comme variable d’environnement — voir Configuration, le schéma de configuration et les variables d’environnement.
  • La frontière du workspace — ce qui se trouve à l’intérieur d’un workspace, l’effet d’un lien symbolique qui en sort sur chaque type de chemin, les chemins qui sortent délibérément, et que faire lorsque l’un d’eux est refusé.
CommandeDescription
aggrega authGérer l’identité de signature
aggrega buildCompiler un Aggregate et une Release en artefacts natifs du provider sous dist/ à la racine du workspace
aggrega cacheInspecter et entretenir les caches sur disque
aggrega configInspecter et gérer la configuration du workspace
aggrega deprecateAttacher un marqueur de dépréciation signé à un artefact déjà publié
aggrega edit-documentAppliquer à un document une modification structurée et circonscrite, en préservant chaque octet qu’elle ne touche pas
aggrega explainExpliquer la condition d’arrêt que nomme un code
aggrega get-schemaAfficher le JSON Schema d’un type d’entité ou de contrat
aggrega importTransformer la description d’une source externe en brouillons de fichiers d’écriture Aggrega
aggrega inspectInspecter une entité de catalogue par son nom, un fichier d’entité par son chemin ou une entité publiée par sa référence de registry
aggrega lintVérifier les conventions de publication du catalogue sur le catalogue, une Release ou une seule entité
aggrega loginS’authentifier auprès d’un registry OCI et stocker l’identifiant
aggrega logoutSupprimer un identifiant de registry stocké
aggrega mcpExécuter un serveur Model Context Protocol sur l’entrée et la sortie standard, ou sur HTTP, pour l’intégration d’assistants IA
aggrega pinEnregistrer les épinglages de contenu des entrées externes d’une entité dans l’entity.lock situé à côté
aggrega pluginInspecter les plugins Wasm que la CLI peut résoudre
aggrega pullRésoudre les dépendances de catalogue et de source dans le cache et écrire le lockfile par Release
aggrega pushEmpaqueter et publier une entité de catalogue dans un registry OCI
aggrega push-artifactPublier un artefact de données autonome (tel qu’un lot de documentation) dans un registry OCI
aggrega registryGérer les registries et leur politique de confiance des signatures
aggrega scaffoldRédiger un document de départ pour un type d’entité, ou écrire un exemple exécutable dans un nouveau répertoire
aggrega searchRechercher dans l’index local des registries configurés
aggrega serveS’exécuter comme compilateur-service de longue durée via JSON-RPC 2.0 sur stdin/stdout
aggrega signSigner un ou plusieurs artefacts déjà publiés et y attacher leurs signatures
aggrega skillsInstaller la skill Aggrega dans un assistant IA
aggrega validateVérifier la correction sur le catalogue, une Release ou une seule entité
aggrega versionAfficher la version de la CLI aggrega

Arguments positionnels et code de sortie

Chaque commande refuse un argument positionnel dont elle n’a pas l’usage, et signale ce refus par un code de sortie non nul au lieu de se terminer comme si l’invocation était valide. La règle couvre les commandes qui n’existent que pour regrouper des sous-commandes, où un nom de sous-commande mal saisi arrive comme un argument positionnel non reconnu : l’aide de la commande est affichée et le code de sortie est non nul, de sorte qu’une faute de frappe dans un script échoue de façon visible au lieu de passer pour une exécution réussie. aggrega invoqué avec une commande non reconnue se comporte de la même façon et nomme en plus la commande la plus proche, lorsqu’il y en a une suffisamment proche.

Une commande non reconnue indique aussi comment trouver un plugin de CLI portant ce nom. La réponse vient de l’index local du registre par défaut que aggrega registry update construit et que aggrega search lit ; elle arrive donc immédiatement et le mot mal saisi n’est jamais envoyé à un registre, en ligne ou hors ligne. Lorsque l’index contient un plugin de CLI portant ce nom, le message nomme la commande aggrega plugin add cli <name> qui l’installe. Lorsque l’index n’en contient aucun, il nomme la recherche qui en cherche un, aggrega search <name> --kind plugin --plugin-type cli. Lorsqu’aucun index n’a encore été construit, il nomme aggrega plugin add cli <name>, qui recherche le plugin sous ce nom dans le registre et refuse lorsqu’aucun n’est publié. Chacune de ces commandes porte le nom mis entre guillemets pour le shell lorsque c’est nécessaire.

Là où les arguments positionnels ont un sens, la page de référence de chaque commande documente ce qu’elle accepte. Un plugin de CLI installé est l’exception délibérée : sa commande se réserve l’analyse des arguments, de sorte que le vecteur d’arguments entier est transmis au plugin, seul à analyser ses propres arguments — et le code de sortie du plugin lui-même est ce que renvoie l’invocation.

Progression, et durée d’attente d’une commande auprès d’un registre

Une commande qui attend indique ce qu’elle attend. Partout où une commande attend un registre, un téléchargement ou la première compilation d’un plugin, elle affiche cette étape sur la sortie d’erreur standard, comme aggrega build et aggrega pull affichent les leurs : sur un terminal, une ligne nommant l’étape avec un indicateur rotatif et le temps écoulé jusque-là, cochée une fois l’étape terminée et laissée non cochée lorsque l’étape a échoué ; sur un terminal qui ne peut pas redessiner sur place, ou avec --plain, une ligne par étape à la fin de celle-ci, avec sa durée. Lorsque la sortie d’erreur standard n’est pas un terminal, rien n’est affiché, et rien de ce qu’une commande écrit sur la sortie standard ne change dans un cas comme dans l’autre. Une étape n’est affichée que pendant que la commande l’attend réellement : une exécution servie depuis le cache n’affiche donc rien du tout, et la compilation d’un plugin n’est affichée que lorsqu’elle dure assez longtemps pour être une véritable compilation plutôt qu’une compilation mise en cache.

Les commandes qui affichent leurs étapes de cette manière, en plus de la commande de chaque plugin de CLI installé :

aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate

Aucune requête n’attend un serveur indéfiniment. Une requête attend au plus 30 secondes que le serveur commence sa réponse une fois la requête entièrement envoyée, et au plus 30 secondes la partie suivante d’une réponse qui arrive déjà. Un serveur qui fait attendre une requête plus longtemps est refusé sous E0376, avec le nom du serveur et la durée d’attente. Seule l’attente est bornée : un téléchargement ou un envoi qui continue de progresser prend le temps qu’il faut. Un chart Helm que le source: d’une Recipe récupère en HTTPS n’est soumis qu’à la première des deux attentes, et son expiration est signalée dans les termes propres de la bibliothèque réseau plutôt que sous E0376. Une requête qu’une commande renvoie déjà lorsqu’elle expire — une lecture pendant aggrega registry update, une écriture pendant une publication — est renvoyée avant que le refus ne soit signalé.

Le parcours de la liste complète des dépôts d’un registre se termine en cinq minutes au plus. Certains registres rassemblent tous les dépôts qu’ils contiennent avant même de répondre à une requête de liste ; chaque page de la liste est donc attendue aussi longtemps que le parcours peut durer plutôt que 30 secondes ; une liste qui n’est pas terminée au bout de cinq minutes est interrompue et refusée sous E0377. aggrega plugin add ne parcourt la liste que lorsqu’aucun plugin ne porte exactement le nom qu’il a reçu, afin d’en trouver un dont le nom le contient ; nommer le plugin exactement n’attend donc jamais le parcours.

Un registre qui demande de ralentir est attendu, jusqu’à ce qu’il l’ait demandé pendant cinq minutes sans interruption. Une commande attend aussi longtemps qu’un tel registre le demande, lui envoie moins de requêtes à la fois et affiche l’attente avec le reste de sa progression ; un registre qui ne répond rien d’autre que « ralentissez » pendant cinq minutes est refusé avec E0378. Un registre qui demande de ralentir décrit comment.

Les trois limites sont fixes ; aucun paramètre ne les modifie.

Les chemins que vous saisissez, et la frontière du workspace

Un chemin que vous saisissez sur la ligne de commande — un --release, un --catalog, un --output-dir, un fichier à valider, à analyser avec le linter, à épingler ou à publier, un --workspace-root — est utilisé là où il mène, dans le workspace ou en dehors, à travers tout lien rencontré en chemin. Ce que la commande lit et écrit ensuite pour son propre compte reste confiné au workspace, quel que soit l’utilisateur qui l’exécute : elle ne lit pas les fichiers de configuration du workspace, un document du catalogue, un document à côté d’une Release ou le fichier de verrouillage d’une Release à travers un lien qui sort du workspace, ne suit pas un chemin qu’une Release ou un Manifest écrit hors de celui-ci, et n’écrit pas sa sortie, son fichier de verrouillage ou son cache à travers un tel lien. Un répertoire que vous désignez hors du workspace est confiné de la même façon pour ce qu’il contient, et une Release que vous désignez hors du workspace n’atteint que les fichiers de son propre répertoire. aggrega edit-document est la seule commande dont le chemin saisi est lui aussi confiné : elle ne modifie qu’un document que contient le workspace. La frontière du workspace énonce la règle, les chemins qui sortent volontairement, et le remède à chaque refus.

Rechercher dans l’index du catalogue

aggrega search [query] recherche les entités publiées dans les registres que connaît le workspace. Le paramètre facultatif [query] est une sous-chaîne, insensible à la casse, comparée au nom et à la description de chaque entité. Des filtres par facette restreignent l’ensemble des résultats :

  • --kind restreint à un ou plusieurs types d’entité (component, feature, recipe, featurerecipe, workload, plugin) ; il est répétable et insensible à la casse, et les types se combinent en OU.
  • -l/--selector filtre sur les labels de catalogue de l’entité. La catégorie est un label, pas un flag dédié : -l component.aggrega.ai/category=datastore.
  • --capability et --plugin-type filtrent les plugins par capacité déclarée ou par type de socket ; --capability est répétable et se combine en OU.
  • --registry limite la recherche à un seul registre, désigné par son hôte ou par un alias ; par défaut, tous les registres configurés sont interrogés.
  • --limit plafonne le nombre de résultats.
  • -o/--output sélectionne le format de sortie : table (par défaut, lisible par un humain), json (un tableau lisible par une machine) ou names (identifiants seuls, un par ligne).

La recherche lit toujours l’index local — l’instantané hors ligne que aggrega registry update construit et actualise. Elle ne contacte aucun réseau et ne récupère rien à la demande. Lorsque l’index est absent, la commande échoue et vous indique d’exécuter d’abord aggrega registry update. Chaque exécution affiche sur la sortie d’erreur standard, pour chaque registre, une ligne de fraîcheur « last updated », de sorte que la sortie json et names sur la sortie standard reste propre pour les scripts.

Complétion du shell

aggrega completion <shell> affiche sur stdout un script de complétion pour bash, zsh, fish ou powershell. Le script est généré à partir de l’arborescence de commandes active de la CLI au moment où vous l’exécutez, il reflète donc toujours les commandes et les flags du binaire qui l’a produit — il n’y a aucun fichier statique à régénérer à mesure que la CLI évolue.

Pour essayer la complétion dans votre session actuelle sans rien installer, chargez directement le script avec source :

Terminal window
source <(aggrega completion bash)

Pour installer la complétion de façon permanente, écrivez le script à l’emplacement que votre shell lit au démarrage.

bash

La complétion Bash repose sur le paquet bash-completion ; installez-le avec le gestionnaire de paquets de votre système d’exploitation s’il n’est pas déjà présent.

Terminal window
# Linux
aggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)
aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggrega

zsh

Si la complétion n’est pas encore activée dans votre shell, activez-la une fois :

Terminal window
echo "autoload -U compinit; compinit" >> ~/.zshrc

Écrivez ensuite le script de complétion dans un répertoire de votre fpath :

Terminal window
# Linux
aggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)
aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggrega

fish

Terminal window
aggrega completion fish > ~/.config/fish/completions/aggrega.fish

powershell

Ajoutez le script généré à votre profil PowerShell pour qu’il soit chargé dans chaque session :

Terminal window
aggrega completion powershell >> $PROFILE

Démarrez un nouveau shell pour que la complétion installée prenne effet.