aggrega scaffold
Rédiger un document de départ pour un type d’entité, ou écrire un exemple exécutable dans un nouveau répertoire
Synopsis
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]Description
Draft a starter document for an entity kind from its schema, or write one of the documentation's runnable examples into a new directory.
Drafting a starter document
The kind is the lowercase-hyphenated schema token — for example component, aggregate, release, recipe, manifest, or feature. Run aggrega get-schema --list to print the whole set; a token no schema answers to is refused with that set in the message, so a typo is corrected without a second lookup.
The document is derived from that kind's own contract and from nothing else. It carries exactly the fields that kind's schema requires, with the fixed apiVersion and kind filled in and a placeholder everywhere a value is needed. It is not a worked example: there is no namespace, no category, no label set and no commented suggestion of what people usually write, because a catalog decides those for itself and a starter document that guessed at them would teach a requirement that does not exist.
The optional name seeds metadata.name for a kind whose schema requires one. Every other required value is left as a placeholder to fill in.
Nothing is written to disk. The document goes to standard output, so a redirect decides where it lands:
aggrega scaffold component my-service > my-service.yaml
The same starter document is served to an assistant by the scaffold tool that aggrega mcp exposes, which returns these bytes alongside a machine-readable payload; this command is the terminal route to the same drafting.
Writing a runnable example
With --example, the argument is the name of one of the runnable examples the documentation publishes, and the command writes that example's files into a new directory — the second argument, or a directory named after the example in the current directory when there is none — then prints the commands the example's own page gives for building it:
aggrega scaffold --example redis-cache
The directory must not exist yet, or must be empty; a directory holding anything is refused and left as it is. With --list, the command prints every example there is, each with its level and the first sentence of its page, and writes nothing:
aggrega scaffold --example --list
The examples are read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version. It is kept in the cache every project on this machine shares, so a second example needs no second download. It is fetched through the same network settings as every other registry read, and verified against this workspace's signature policy before it is kept or read; a bundle that does not verify is refused, never used. Offline, an example is written only from a copy already cached on this machine.
An example's files are written only as files and directories inside the directory named: a bundle carrying an entry that would land outside it, or a link, is refused whole and nothing is written.
The scaffold tool that aggrega mcp exposes, and the editor's language server that aggrega serve runs, write and list the examples on the same terms, with the directory named relative to the workspace root, and answer with the files written and these same commands.Options
| Option | Par défaut | Description |
|---|---|---|
--example | false | écrit dans un nouveau répertoire l’exemple exécutable que nomme l’argument, lu depuis le bundle signé de la documentation |
--list | false | avec —example, affiche chaque exemple exécutable que publie la documentation, et n’écrit rien |
Fonctionnement
La commande a deux formes. aggrega scaffold <kind> rédige un document de départ à partir du schéma d’un type et l’affiche ; c’est ce que décrivent cette section et les trois suivantes. aggrega scaffold --example <name> écrit à la place l’un des exemples exécutables de la documentation dans un nouveau répertoire — voir Partir d’un exemple exécutable.
aggrega scaffold <kind> affiche sur la sortie standard un document de départ pour un type d’entité. Le document contient exactement les champs que le schéma de ce type exige : apiVersion et kind sont remplis, car le schéma les fixe, et toute autre valeur requise est laissée sous forme d’espace réservé à remplacer.
Le [name] facultatif initialise metadata.name pour un type dont le schéma en exige un :
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}Le type est le jeton de schéma en minuscules avec traits d’union — component, aggregate, release, recipe, manifest, feature, etc. aggrega get-schema --list affiche l’ensemble complet, et un jeton auquel ne correspond aucun schéma est refusé avec cet ensemble dans le message, de sorte qu’une faute de frappe se corrige sans seconde recherche.
Ce qu’il renvoie, et ce qu’il ne renvoie pas
Le document provient du contrat propre au type et de rien d’autre. Ce n’est pas un exemple travaillé. Il n’y a ni namespace, ni catégorie, ni valeurs de label remplies pour vous, ni suggestion en commentaire de ce que l’on écrit habituellement — car rien de tout cela n’est exigé par le compilateur. Un catalogue choisit son propre nommage, ses propres catégories et sa propre arborescence ; le schéma décide des champs, et le schéma est tout ce que cette commande lit. Un document de départ qui devinerait le reste vous enseignerait une règle qui n’existe pas.
Ébaucher un document n’écrit aucun fichier. Le document va sur la sortie standard, de sorte qu’une redirection décide où il arrive, et rien sur le disque n’est remplacé sans que vous le demandiez :
aggrega scaffold component my-service > my-service.yamlCe n’est pas une entité finie, et c’est ce que signifie un espace réservé. Une valeur requise vide n’est pas une valeur, donc exécuter aggrega validate sur le document tel qu’il est sorti le refuse et nomme d’un coup chaque espace réservé encore dû, chacun avec ce qu’il accepte — ci-dessus, la version et le type de composant :
Entity: my-service.yamlKind: Component[E0215] document envelope validation failed: 2 placeholders still owed in my-service.yaml; an empty required value is not a value, so each of these needs one before the document validates: 5:3: metadata.version takes a semantic version, such as 1.0.0 7:5: metadata.labels.component.aggrega.ai/type takes one of: server, worker, task, function, stateful-server, resourceCe que chaque valeur accepte est lu dans le schéma propre au type : les valeurs qu’il accepte lorsque le schéma les liste, une version sémantique lorsqu’il en demande une, et sinon la description du champ fournie par le schéma lui-même. Fournissez ces valeurs et la même commande accepte le document. Rien de sa forme n’a à changer, car la forme vient du schéma.
Une valeur est due même là où le schéma l’accepterait vide. Une Recipe ou FeatureRecipe générée porte un capability et un implements vides. Leur schéma admet une chaîne vide, mais une chaîne vide ne nomme aucun provider ni aucun type, donc aggrega validate les signale tous deux comme encore dus jusqu’à ce que vous les remplissiez. Cette lecture relève de la validation d’un seul fichier d’entité : une exécution sur tout le catalogue, aggrega validate --release et aggrega build ne l’appliquent pas. Voir espaces réservés encore dus pour ce qu’elle couvre. Une Recipe générée ne déclare par ailleurs aucun des types d’entrée dont son schéma exige au moins un — source, valuesMapping, workload ou artifacts — car le choix de celui qui convient vous revient ; aggrega validate refuse donc son spec jusqu’à ce que vous en ajoutiez un.
Le même document depuis un assistant ou un éditeur
Le document de départ est constitué des mêmes octets quelle que soit l’interface qui le demande. Un assistant d’IA connecté via aggrega mcp l’obtient en tant qu’outil scaffold, qui renvoie le document sous forme de texte avec une charge utile lisible par une machine. Un éditeur qui pilote aggrega serve l’obtient via aggrega/scaffoldEntity. Le document est dérivé du schéma une seule fois, de sorte que celui que vous générez dans un terminal et celui qu’un assistant génère pour vous sont identiques octet pour octet.
L’écriture et la liste des exemples exécutables sont disponibles sur les mêmes surfaces, avec les mots de la commande elle-même comme noms de champs. Envoyez à l’outil scaffold, ou à aggrega/scaffoldEntity, example au lieu de kind pour en écrire un, dir pour nommer le nouveau répertoire relativement à la racine de l’espace de travail — à cet endroit, un répertoire nommé d’après l’exemple lorsque vous n’en envoyez aucun — et list: true seul pour recevoir en réponse tous les exemples. L’exemple est lu dans le même paquet, vérifié selon la même politique et écrit par la même extraction ; les fichiers et les commandes suivantes sont donc les mêmes qu’au terminal, tout comme les refus : un répertoire qui contient quoi que ce soit, une entrée qui sort du répertoire ou qui est un lien, un paquet que votre politique n’accepte pas, un espace de travail hors ligne sans rien en cache. La réponse est structurée : pour une liste, examples, chacun avec son name, son level et son summary ; pour une écriture, example, dir, files — les fichiers écrits, relatifs à dir —, next, les commandes que donne la page de l’exemple, et version, la version de la documentation dans laquelle l’exemple a été lu. La réponse de l’outil scaffold à une écriture porte aussi output_dir, l’emplacement du répertoire — complet sur l’entrée et la sortie standard, afin qu’un assistant qui l’a nommé relativement à un espace de travail qu’il ne peut pas voir lise où l’exemple a été écrit, et relatif à la racine de l’espace de travail sur HTTP. Le texte de l’outil scaffold est le compte rendu qu’affiche cette commande, terminé par une ligne qui nomme cet emplacement lorsqu’il diffère de dir. Des champs de deux formes envoyés ensemble — kind avec example, par exemple — sont refusés dans les mêmes termes sur les deux surfaces, avant toute lecture. Un éditeur nomme l’espace de travail dans le workspaceRoot de la requête pour la forme exemple, et dir doit être un chemin relatif qui reste à l’intérieur de celui-ci et n’en sort pas par un lien ; sur HTTP, l’outil tient lui aussi dir à l’espace de travail qu’il sert, et sur l’entrée et la sortie standard il prend dir tel qu’il est nommé, comme il prend tout chemin. L’index des capacités signale l’outil scaffold comme écrivant, en raison de cette forme, et cli-scaffold, qui exécute cette commande dans un processus distinct, comme écrivant lui aussi.
Partir d’un exemple exécutable
La documentation contient des exemples exécutables — chacun est un répertoire contenant un Aggregate, ses Releases et tout ce à partir de quoi il se construit, avec une page expliquant comment le construire. --example en écrit un dans un nouveau répertoire, afin que vous puissiez partir d’un projet qui fonctionne plutôt que d’un projet vide :
aggrega scaffold --example redis-cacheWrote the example redis-cache into redis-cache (12 files).
Next:
cd redis-cache # Local development (Docker Compose), no authentication aggrega build --release release-compose.yaml --auto-pull ...
Its page, redis-cache/README.md, explains what it shows.Ce qu’il écrit, et où. Les fichiers de l’exemple, tels que la documentation les contient, dans le répertoire que vous nommez en deuxième argument — ou, si vous n’en nommez aucun, dans un répertoire portant le nom de l’exemple dans le dossier où vous exécutez la commande. Le répertoire ne doit pas encore exister, ou doit être vide. Tout autre cas est refusé et laissé exactement tel qu’il était : un répertoire qui contient un fichier, un fichier situé à ce chemin, ou un lien. Les répertoires au-dessus de lui qui n’existent pas encore sont créés. Aucun fichier de l’exemple n’est laissé ailleurs, et aucun n’est mis en place avant que tous soient écrits : ils sont d’abord écrits à part, puis déplacés une fois que chacun d’eux est là.
Les commandes qu’il affiche ensuite sont celles que donne la page de l’exemple elle-même : le premier bloc sh, bash ou shell sous le titre ## Build de la page, tel que la page l’écrit, commentaires compris, après un cd dans le répertoire. Pour un exemple dont la page n’a aucun bloc de ce type, la réponse est plutôt le chemin de sa page.
Quels exemples existent. --list affiche chaque exemple, une fois chacun, dans l’ordre où la documentation les enseigne — son nom, le niveau que déclare sa page et la première phrase de sa page — et n’écrit rien :
aggrega scaffold --example --listEXAMPLE LEVEL DESCRIPTION...redis-cache start This lean example compiles a single **Redis** in-memory cache (Redis wire protocol) from one Developer-authored `Aggregate` to two realizations....La liste est la liste d’exemples de la documentation elle-même, celle qui est publiée à côté d’eux sous le titre Exemples par produit et capacité. Un nom sous lequel le paquet ne contient aucun exemple est refusé, en vous renvoyant à --list, et rien n’est écrit.
D’où viennent les exemples. Ils sont lus dans le paquet de documentation — l’archive signée de la documentation publiée dans laquelle aggrega explain lit ses explications pas à pas — publié sur le registre par défaut de votre espace de travail. Le paquet lu est celui publié pour la version d’aggrega que vous exécutez. Si aucun n’est publié pour cette version, c’est le plus récent publié pour une version antérieure, et la commande le signale sur la sortie d’erreur standard :
note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before itUne build d’aggrega faite à partir de quelques commits postérieurs à une version publiée — une build dont aggrega version se lit comme 0.9.0-12-g1a2b3c4d — lit la documentation de la version après laquelle elle a été construite, ici 0.9.0, ou d’une version antérieure si celle-ci n’est pas publiée. Une build faite à partir de quelques commits postérieurs à une préversion, comme une version candidate — une build dont aggrega version se lit comme 0.9.0-rc.6-4-gc9db2f597 — lit la documentation de cette préversion, ici 0.9.0-rc.6, ou, si celle-ci n’est pas publiée, la plus récente publiée avant elle, préversion antérieure comprise. Toute autre build ne lit la documentation d’une préversion que lorsqu’elle est elle-même cette préversion. Une build qui ne porte aucun numéro de version lit la documentation de sa propre version, ou aucune. aggrega explain choisit de la même manière le paquet dans lequel il lit ses explications pas à pas.
Lorsqu’aucun n’est publié pour votre version et que le plus récent des antérieurs est dans un format que cette version d’aggrega ne lit plus — une version candidate exécutée avant la publication de sa propre documentation, par exemple —, la commande refuse, en indiquant les deux en une seule phrase, et rien n’est écrit :
[E0137] hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the examples cannot be readIl est vérifié avant d’être utilisé. Le paquet est récupéré avec les mêmes paramètres réseau que toute autre lecture de registre, et sa signature est vérifiée selon la politique de signature de votre espace de travail pour ce registre avant qu’il soit conservé — et de nouveau avant qu’une copie déjà présente sur la machine soit lue, de sorte qu’une copie admise par la politique plus souple d’un autre projet n’est pas utilisée sous la vôtre. Un paquet que votre politique n’accepte pas est refusé, et rien n’est écrit.
Il est récupéré une fois par machine. Le paquet est conservé dans le cache que partagent tous les projets Aggrega de la machine — voir aggrega cache — de sorte qu’un deuxième exemple, ou un deuxième projet, ne nécessite pas de deuxième téléchargement, et aggrega explain lit la même copie lorsque les deux lisent la même version.
Hors ligne, il ne lit que ce qui est en cache. Dans un espace de travail hors ligne, rien n’est récupéré : un exemple est écrit à partir d’une copie déjà présente sur la machine que votre politique admet — celle de cette version, ou sinon la plus récente des versions antérieures en cache — et, s’il n’y en a aucune, la commande refuse avec le refus hors ligne que donne toute lecture réseau, en indiquant comment autoriser le réseau.
Un paquet contenant quelque chose d’inattendu est refusé en entier. Le paquet provient d’un registre ; l’extraction ne fait donc confiance à rien de sa structure : une entrée dont le nom aboutirait hors du répertoire que vous avez nommé, ou hors du paquet, et une entrée qui est un lien ou autre chose qu’un fichier ou un répertoire refusent chacune l’exemple entier, en nommant l’entrée, et rien n’est écrit. Un fichier exécutable de l’exemple reste exécutable.
La configuration de l’espace de travail est lue. Le registre par défaut et la politique de signature en proviennent ; un fichier de configuration qui est un lien sortant de l’espace de travail arrête donc la forme exemple comme il arrête toute autre commande qui lit la configuration — voir la limite de l’espace de travail.
Exemples
Générer une Release sans nom et la lire dans le terminal :
aggrega scaffold releaseGénérer une Recipe directement dans un fichier :
aggrega scaffold recipe postgres-helm > postgres-helm.yamlVérifier ce qu’il vous reste à fournir avant de remplir quoi que ce soit :
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlVoyez quels exemples exécutables existent, puis écrivez-en un dans un répertoire de votre choix :
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cachePour la boucle de rédaction que cette commande amorce — esquisser la forme, remplir les espaces réservés, valider —, voir Rédiger des fichiers Aggrega.