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

aggrega edit-document

Appliquer à un document une modification structurée et circonscrite, en préservant chaque octet qu’elle ne touche pas

Synopsis

aggrega edit-document <edit> <file> [flags]

Description

Apply one bounded structured edit to a document in the workspace.
The edit is named first and the document second. One call adds one entry under one container, or sets one scalar, and it can do nothing else:
add-component add a component instance under a components container
attach-feature attach a Feature to the node you name
wire-edge wire a connection inside one of that node's sockets
set-value set one value on that node
There is no edit that deletes, replaces a block you already wrote, reorders anything, or writes bytes you supply verbatim. The edits this command applies are add-component, attach-feature, wire-edge, set-value, and a name outside that set is refused rather than interpreted.
Name the node with --node, once per path segment, from the document root. It is a segment at a time rather than one dotted string because a dot is a legal character in a name you type, so a joined path could address a key nobody wrote and the entry would be created there rather than refused:
aggrega edit-document add-component app.yaml \
--node spec --node components --name web --value example/service
aggrega edit-document wire-edge app.yaml \
--node spec --node components --node web \
--socket database --name db --value spec.components.store
For add-component the path names the components container itself, because the entry being added is the node. For the other three it names the node the edit is about, and the container follows from the edit.
--name is the key the entry is written under: the instance name, the attachment's name, the connection's alias, or the value's key. --value is what that entry carries, and what it means follows from the edit — the entity the entry requests, the node a connection points at, or the scalar a value is set to. It is read as a YAML scalar, so --value 3 sets a number, --value true a boolean, and --value '"3"' the string; omitting it sets nothing at all.
Every byte the edit does not touch survives. The document is parsed only to locate the container and the line its block ends at, so comments, blank lines, quoting style, folded and literal scalars and the trailing-newline shape all carry through, and the nesting step is measured from the document's own indentation rather than imposed. The same request against the same document produces the same bytes.
The result has to be a document you could have typed, and that is what the write is gated on: the composed document is checked against its own kind's schema and reaches disk only if that passes. A request that would produce something the schema refuses is refused, naming the property the schema would not admit and where, and the file is left byte-for-byte as it was — so a refused edit is indistinguishable from one never attempted and you can retry a corrected request against the document you started with.
An entry that is already there, carrying what you asked for, is a no-op. An entry of that name carrying something else is refused rather than replaced.
--dry-run does everything the plain command does except write: the edited document goes to standard output as content, naming the file it is for, and nothing is created — for a caller that puts the result in front of someone before it is saved. Every other behaviour is the write's, the schema gate included, so a request the write would refuse is refused under --dry-run too and its exit code predicts the write's. Without it the document is written.
Whether what you wire is semantically admissible is not decided here. Whether a socket is one the producer declares, or whether a Feature's applicability is satisfied, is what aggrega validate answers.

Options

OptionPar défautDescription
--dry-runfalseTout faire sauf écrire : renvoyer le document modifié sous forme de contenu, en nommant le fichier auquel il est destiné, et ne rien créer ni modifier. Tout autre comportement est celui de l’écriture, contrôle par le schéma compris. Sans cette option, le document est écrit
--name—La clé sous laquelle la nouvelle entrée est écrite : le nom de l’instance du composant, le nom du rattachement, l’alias de la connexion ou la clé de la valeur
--node[]Un segment du chemin structurel vers le nœud concerné par la modification, à partir de la racine du document. Répétez-la une fois par segment, le plus externe en premier. Elle prend un segment à la fois plutôt qu’un seul chemin pointé parce qu’un point est un caractère autorisé dans un nom que vous saisissez, si bien qu’un chemin joint pourrait adresser une clé que personne n’a écrite
--socket—Le socket de dépendance à l’intérieur duquel une connexion est câblée. Lu pour wire-edge et ignoré sinon
--value—Ce que porte l’entrée, lu comme un scalaire YAML. Sa signification découle de la modification : l’entité que l’entrée demande, le nœud vers lequel pointe une connexion ou le scalaire auquel une valeur est fixée

Fonctionnement

aggrega edit-document <edit> <file> applique une modification structurée à un document de votre workspace et laisse chaque octet qu’elle n’a pas touché exactement tel que vous l’avez écrit. La modification est nommée en premier et le document en second :

Terminal window
aggrega edit-document add-component storefront.aggregate.yaml \
--node spec --node components \
--name checkout --value core/api-server:1.0.0

Elle existe pour le cas où vous préférez que le fichier soit modifié plutôt que de vous voir indiquer où le modifier. Si vous gérez votre propre buffer et votre propre historique d’annulation, aggrega serve indique une position et vous laisse placer le texte vous-même ; cette commande compose l’entrée et l’écrit.

Le document est un document que contient votre workspace. Nommez-le relativement à la racine du workspace ou par son chemin absolu ; un document extérieur au workspace est refusé sans que rien ne soit lu ni écrit, qu’il soit écrit ainsi ou atteint par un lien menant hors du workspace — un lien vers le fichier, ou un répertoire sur le chemin qui est un lien. Une modification lit le document avant de le réécrire, donc un document derrière un tel lien est un fichier que le workspace ne contient pas, et le refus l’indique :

the document named leads outside the workspace through a link, and an edit is only applied to a document the workspace carries: "shared/storefront.aggregate.yaml"

Pour modifier un document conservé ailleurs, exécutez la commande dans le workspace qui le contient. Les modifications du serveur de langage et des outils de l’assistant appliquent la même règle, car tous trois appliquent une seule et même modification. Son document est le seul chemin que vous saisissez qui soit restreint au workspace, comme l’expose La frontière du workspace.

Un appel, une entrée, et l’ensemble est fermé

Il existe quatre modifications et aucune autre :

ModificationCe qu’elle ajoute
add-componentune instance de composant sous un conteneur de composants
attach-featureun rattachement de Feature sur le nœud que vous nommez
wire-edgeune connexion à l’intérieur de l’un des sockets de dépendance de ce nœud
set-valueune valeur sur le nœud que vous nommez

Aucune modification ne supprime, ne remplace un bloc que vous avez déjà écrit, ne réordonne quoi que ce soit ni n’écrit telles quelles des octets que vous fournissez. C’est la conception tout entière plutôt qu’une restriction de celle-ci : un nom hors des quatre n’a aucun chemin à travers la commande, il ne s’agit donc pas d’un outil d’écriture de fichiers sous un nom plus étroit. Un nom hors de l’ensemble est refusé plutôt qu’interprété.

Une entrée déjà présente, qui porte ce que vous avez demandé, est sans effet — la commande l’indique et n’écrit rien :

storefront.aggregate.yaml already carries that entry; nothing was written

Une entrée de ce nom qui porte autre chose est refusée plutôt que remplacée, car remplacer ce que vous avez écrit ne fait pas partie des quatre.

Vous nommez le nœud sous forme de chemin, un segment à la fois

--node est répété une fois par segment du chemin depuis la racine du document, le plus externe en premier :

Terminal window
aggrega edit-document wire-edge storefront.aggregate.yaml \
--node spec --node components --node web \
--socket database --name replica --value store

Elle prend un segment à la fois plutôt qu’un seul chemin pointé à dessein, et la raison tient à l’exactitude. Un point est un caractère autorisé dans un nom que vous saisissez, donc rien en dehors du document ne peut distinguer un point structurel d’un point à l’intérieur d’un nom. Un chemin joint se lirait correctement et adresserait une clé que personne n’a écrite — et comme add-component peut créer un conteneur que le document ne contient pas, l’entrée atterrirait sous cette clé inventée au lieu d’être refusée. Les segments éliminent l’ambiguïté au lieu de la déplacer.

Pour add-component, le chemin nomme le conteneur de composants lui-même, car l’entrée ajoutée est le nœud. Pour les trois autres, il nomme le nœud concerné par la modification, et le conteneur découle de la modification : un rattachement va sous le features de ce nœud, une connexion sous son uses et le socket que vous avez nommé, une valeur sous son values.

--name est la clé sous laquelle l’entrée est écrite — le nom de l’instance, le nom du rattachement, l’alias de la connexion ou la clé de la valeur. --socket est lu pour wire-edge et ignoré sinon.

Une valeur conserve le type que portent ses caractères

--value est lu comme un scalaire YAML, c’est-à-dire de la même façon que les caractères seraient lus si vous les aviez saisis dans le document :

Terminal window
aggrega edit-document set-value storefront.aggregate.yaml \
--node spec --node components --node web --name workers --value 4
values:
replicas: 3
workers: 4

Ainsi, --value 4 définit un nombre, --value true un booléen, et --value '"4"' la chaîne 4 — les guillemets disent ici «ceci est du texte » exactement comme dans le document. Omettre --value ne définit rien du tout. Un mapping ou une séquence est refusé, car en écrire un reviendrait à ajouter un bloc, et cela ne fait pas partie des quatre modifications.

Tout ce que vous n’avez pas modifié est préservé, et la même requête produit les mêmes octets

Le document n’est analysé que pour localiser le conteneur et la ligne où se termine son bloc ; l’entrée est rendue et insérée au niveau de la ligne. Les commentaires, les lignes vides, le style de guillemets, les scalaires pliés et littéraux, les expressions de template et la forme du saut de ligne final sont tous conservés tels quels, et le pas d’imbrication est mesuré à partir de l’indentation propre du document plutôt qu’imposé — ainsi, une entrée s’insère dans le style que vous utilisez déjà.

Pour le même document et la même requête, les octets sont les mêmes à chaque fois. Vous pouvez donc comparer deux exécutions, et une revue lit une modification comme un seul diff.

Le résultat doit être un document que vous auriez pu saisir

C’est à cela qu’est subordonnée l’écriture. Le document composé est vérifié par rapport au schéma de son propre type, lu depuis le document plutôt que fourni par vous, et les octets n’atteignent le disque que si cette vérification réussit. Une requête qui produirait quelque chose que le schéma refuse est refusée, en nommant la propriété que le schéma n’admettrait pas et son emplacement :

the edit was refused because the resulting document would not be valid, and nothing
was written: document envelope validation failed (Release, at prod.release.yaml);
15:7: spec.components.web.values: … unexpected property: "values"

Le fichier reste octet pour octet tel qu’il était, et l’écriture elle-même est atomique, de sorte qu’une modification refusée ou interrompue ne se distingue pas d’une modification jamais tentée et que vous pouvez relancer une requête corrigée sur le document de départ. C’est aussi pourquoi aucune règle de rédaction n’est rappelée ici : demander à un document Release de porter une valeur de développeur est refusé par le même schéma qui refuserait le document saisi à la main.

Ce qui est sémantiquement admissible n’est pas décidé ici. Savoir si un socket de dépendance est l’un de ceux que le producteur déclare, ou si l’applicabilité d’une Feature est satisfaite, relève de la résolution qu’effectue un build. Vous pouvez donc nommer une connexion dont cette commande n’a jamais entendu parler, et un Aggregate peut rédiger un socket que son entité de catalogue ne prédéclare pas ; ce qui peut être consommé à travers un socket reste à déclarer par le producteur. Exécutez aggrega validate en nommant une Release lorsque c’est la question.

Voir le résultat avant qu’il ne soit enregistré

--dry-run fait tout ce que fait la commande simple, sauf écrire : le document modifié part sur la sortie standard sous forme de contenu, en nommant le fichier auquel il est destiné, et rien n’est créé :

Terminal window
aggrega edit-document attach-feature storefront.aggregate.yaml \
--node spec --node components --node web \
--name tls --value core/tls:1.0.0 --dry-run
documents:
- path: storefront.aggregate.yaml
content: |
# The storefront application.
...

Sans cette option, le document est écrit. Le comportement par défaut est l’écriture, car le produit de cette commande est un document modifié et une commande qui en produit un se doit de le livrer — une requête qui ne dit rien de la livraison modifie le fichier.

Tout autre comportement est celui de l’écriture, contrôle de validation compris. Une modification dont le schéma refuserait le résultat est également refusée sous --dry-run, en nommant la même propriété et en laissant le fichier exactement tel qu’il était — ainsi, le code de sortie d’un dry run est celui que l’écriture vous aurait renvoyé.

La même modification depuis un éditeur ou un assistant

Les octets sont les mêmes quelle que soit l’interface qui applique la modification. Un éditeur pilotant aggrega serve l’atteint à aggrega/editDocument, et un assistant IA connecté via aggrega mcp l’atteint sous la forme de l’outil par lequel cette commande y est exposée. L’entrée est composée, insérée et soumise à la validation en un seul endroit, et chaque interface n’est qu’un point d’entrée léger vers celui-ci — ainsi, le document que vous modifiez dans un terminal et celui qu’un éditeur modifie pour vous sont identiques octet pour octet.

Le seul point sur lequel les interfaces diffèrent est les octets qu’elles lisent. Cette commande et la méthode de session lisent toutes deux le fichier sur le disque, jamais un buffer non enregistré : écrire depuis un buffer placerait sur la page un contenu que vous n’aviez pas enregistré sous couvert d’appliquer une seule entrée. Enregistrez d’abord, puis modifiez.

Exemples

Ajouter une instance de composant au niveau supérieur d’un Aggregate :

Terminal window
aggrega edit-document add-component storefront.aggregate.yaml \
--node spec --node components --name checkout --value core/api-server:1.0.0

Rattacher une Feature à un composant rédigé à l’intérieur d’un sous-système :

Terminal window
aggrega edit-document attach-feature storefront.aggregate.yaml \
--node spec --node subsystems --node billing --node components --node ledger \
--name audit-log --value core/observability/audit-log:1.0.0

Définir une valeur sur un composant rédigé à l’intérieur d’un sous-système :

Terminal window
aggrega edit-document set-value storefront.aggregate.yaml \
--node spec --node subsystems --node billing --node components --node ledger \
--name replicas --value 5

Examiner le résultat avant que quoi que ce soit ne soit écrit :

Terminal window
aggrega edit-document wire-edge storefront.aggregate.yaml \
--node spec --node components --node web \
--socket cache --name sessions --value redis --dry-run

Pour savoir à quel conteneur appartient une entrée avant d’en nommer un, et pour lire une position sans rien appliquer, consultez aggrega serve.