aggrega edit-document
Aplicar a um documento uma edição estruturada e delimitada, preservando cada byte que ela não toca
Sinopse
aggrega edit-document <edit> <file> [flags]Descrição
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.Flags
| Flag | Padrão | Descrição |
|---|---|---|
--dry-run | false | Fazer tudo exceto gravar: devolver o documento editado como conteúdo, nomeando o arquivo ao qual ele se destina, e não criar nem modificar nada. Todo o restante do comportamento é o da gravação, incluindo a validação pelo esquema. Sem essa opção, o documento é gravado |
--name | — | A chave sob a qual a nova entrada é gravada: o nome da instância do componente, o nome do vínculo, o alias da conexão ou a chave do valor |
--node | [] | Um segmento do caminho estrutural até o nó a que a edição se refere, a partir da raiz do documento. Repita-a uma vez por segmento, começando pelo mais externo. Ela recebe um segmento por vez em vez de um único caminho com pontos porque o ponto é um caractere válido em um nome que você digita, então um caminho unido poderia endereçar uma chave que ninguém escreveu |
--socket | — | O socket de dependência dentro do qual uma conexão é ligada. Lido para wire-edge e ignorado nos demais casos |
--value | — | O que a entrada contém, lido como um escalar YAML. Seu significado decorre da edição: a entidade que a entrada solicita, o nó para o qual uma conexão aponta ou o escalar para o qual um valor é definido |
O que ele faz
aggrega edit-document <edit> <file> aplica uma edição estruturada a um documento no seu workspace e deixa cada byte que não tocou exatamente como você o escreveu. A edição é nomeada primeiro e o documento depois:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components \ --name checkout --value core/api-server:1.0.0Ele existe para o caso em que você prefere que o arquivo seja editado em vez de ser informado sobre onde editá-lo. Se você mantém seu próprio buffer e seu próprio histórico de desfazer, aggrega serve informa uma posição e deixa você inserir o texto por conta própria; este comando compõe a entrada e a grava.
O documento é um que o seu workspace contém. Nomeie-o em relação à raiz do workspace ou pelo seu caminho absoluto; um documento fora do workspace é recusado sem que nada seja lido ou gravado, seja ele escrito assim ou alcançado por um link que leva para fora do workspace — um link para o arquivo, ou um diretório no caminho que é um link. Uma edição lê o documento antes de gravá-lo de volta, então um documento atrás de um link desses é um arquivo que o workspace não contém, e a recusa informa isso:
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"Para editar um documento mantido em outro lugar, execute o comando no workspace que o contém. As edições do language server e das ferramentas do assistente aplicam a mesma regra, porque as três aplicam uma única edição. O documento dela é o único caminho que você digita que fica restrito ao workspace, como expõe O limite do workspace.
Uma chamada, uma entrada, e o conjunto é fechado
Há quatro edições e nenhuma outra:
| Edição | O que ela adiciona |
|---|---|
add-component | uma instância de componente sob um contêiner de componentes |
attach-feature | um vínculo de Feature no nó que você nomeia |
wire-edge | uma conexão dentro de um dos sockets de dependência desse nó |
set-value | um valor no nó que você nomeia |
Não existe edição que exclua, substitua um bloco que você já escreveu, reordene algo ou grave literalmente bytes fornecidos por você. Esse é o design por inteiro, e não uma restrição sobre ele: um nome fora dos quatro não tem nenhum caminho através do comando, então isto não é um gravador de arquivos com um nome mais restrito. Um nome fora do conjunto é recusado em vez de interpretado.
Uma entrada que já existe, contendo o que você pediu, não tem efeito — o comando informa isso e não grava nada:
storefront.aggregate.yaml already carries that entry; nothing was writtenUma entrada com esse nome que contém outra coisa é recusada em vez de substituída, porque substituir o que você escreveu não é uma das quatro.
Você nomeia o nó como um caminho, um segmento por vez
--node é repetido uma vez por segmento do caminho a partir da raiz do documento, começando pelo mais externo:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket database --name replica --value storeEla recebe um segmento por vez em vez de um único caminho com pontos de propósito, e o motivo é de correção. O ponto é um caractere válido em um nome que você digita, então nada fora do documento consegue distinguir um ponto estrutural de um ponto dentro de um nome. Um caminho unido seria lido corretamente e endereçaria uma chave que ninguém escreveu — e, como add-component pode criar um contêiner que o documento não contém, a entrada iria parar sob essa chave inventada em vez de ser recusada. Os segmentos eliminam a ambiguidade em vez de deslocá-la.
Para add-component, o caminho nomeia o próprio contêiner de componentes, porque a entrada adicionada é o nó. Para as outras três, ele nomeia o nó a que a edição se refere, e o contêiner decorre da edição: um vínculo vai sob features desse nó, uma conexão sob seu uses e o socket que você nomeou, um valor sob seu values.
--name é a chave sob a qual a entrada é gravada — o nome da instância, o nome do vínculo, o alias da conexão ou a chave do valor. --socket é lido para wire-edge e ignorado nos demais casos.
Um valor mantém o tipo que seus caracteres expressam
--value é lido como um escalar YAML, que é a mesma forma como os caracteres seriam lidos se você os tivesse digitado no documento:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node components --node web --name workers --value 4 values: replicas: 3 workers: 4Assim, --value 4 define um número, --value true um booleano e --value '"4"' a string 4 — as aspas dizem “isto é texto” aqui exatamente como no documento. Omitir --value não define nada. Um mapeamento ou uma sequência é recusado, porque gravá-lo seria adicionar um bloco, e isso não é uma das quatro edições.
Tudo o que você não editou é preservado, e a mesma requisição produz os mesmos bytes
O documento é analisado apenas para localizar o contêiner e a linha em que seu bloco termina; a entrada é renderizada e inserida no nível da linha. Comentários, linhas em branco, estilo de aspas, escalares dobrados e literais, expressões de template e o formato da quebra de linha final passam todos sem alteração, e o passo de aninhamento é medido a partir da própria indentação do documento em vez de imposto — assim, uma entrada fica no estilo em que você já escreve.
Dados o mesmo documento e a mesma requisição, os bytes são os mesmos todas as vezes. Assim, você pode comparar duas execuções, e uma revisão lê uma edição como um único diff.
O resultado tem de ser um documento que você poderia ter digitado
É disso que a gravação depende. O documento composto é verificado em relação ao esquema do seu próprio tipo, lido do documento em vez de fornecido por você, e os bytes chegam ao disco apenas se essa verificação passar. Uma requisição que produziria algo que o esquema recusa é recusada, nomeando a propriedade que o esquema não admitiria e onde:
the edit was refused because the resulting document would not be valid, and nothingwas written: document envelope validation failed (Release, at prod.release.yaml);15:7: spec.components.web.values: … unexpected property: "values"O arquivo fica byte a byte como estava, e a própria gravação é atômica, então uma edição recusada ou interrompida é indistinguível de uma que nunca foi tentada, e você pode repetir uma requisição corrigida sobre o documento com que começou. É também por isso que nenhuma regra de autoria é reafirmada aqui: pedir que um documento Release contenha um valor de desenvolvedor é recusado pelo mesmo esquema que recusaria o documento digitado à mão.
O que é semanticamente admissível não é decidido aqui. Se um socket de dependência é um que o produtor declara, ou se a aplicabilidade de uma Feature é satisfeita, cabe à resolução que um build realiza. Então você pode nomear uma conexão da qual este comando nunca ouviu falar, e um Aggregate pode escrever um socket que sua entidade de catálogo não pré-declara; o que pode ser consumido através de um socket continua cabendo ao produtor declarar. Execute aggrega validate nomeando uma Release quando essa for a questão.
Ver o resultado antes de salvá-lo
--dry-run faz tudo o que o comando simples faz, exceto gravar: o documento editado vai para a saída padrão como conteúdo, nomeando o arquivo ao qual se destina, e nada é criado:
aggrega edit-document attach-feature storefront.aggregate.yaml \ --node spec --node components --node web \ --name tls --value core/tls:1.0.0 --dry-rundocuments: - path: storefront.aggregate.yaml content: | # The storefront application. ...Sem essa opção, o documento é gravado. O padrão é a gravação, porque o produto deste comando é um documento editado, e um comando que produz um deve entregá-lo — uma requisição que não diz nada sobre a entrega edita o arquivo.
Todo o restante do comportamento é o da gravação, incluindo a validação. Uma edição cujo resultado o esquema recusaria também é recusada com --dry-run, nomeando a mesma propriedade e deixando o arquivo exatamente como estava — assim, o código de saída que você obtém de uma execução de teste é o código de saída que a gravação teria dado.
A mesma edição a partir de um editor ou de um assistente
Os bytes são os mesmos qualquer que seja a superfície que aplique a edição. Um editor que controla aggrega serve a acessa em aggrega/editDocument, e um assistente de IA conectado por meio de aggrega mcp a acessa como a ferramenta pela qual este comando é exposto ali. A entrada é composta, inserida e submetida à validação em um único lugar, e cada superfície é um ponto de entrada fino para ele — assim, o documento que você edita em um terminal e o documento que um editor edita para você são idênticos byte a byte.
O único ponto em que as superfícies diferem é quais bytes elas leem. Este comando e o método de sessão leem ambos o arquivo em disco, nunca um buffer não salvo: gravar a partir de um buffer colocaria na página conteúdo que você não havia salvado sob o pretexto de aplicar uma única entrada. Salve primeiro, depois edite.
Exemplos
Adicionar uma instância de componente no nível superior de um Aggregate:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components --name checkout --value core/api-server:1.0.0Vincular uma Feature a um componente escrito dentro de um subsistema:
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.0Defina um valor em um componente escrito dentro de um subsistema:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name replicas --value 5Revisar o resultado antes que qualquer coisa seja gravada:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket cache --name sessions --value redis --dry-runPara descobrir a qual contêiner uma entrada pertence antes de nomear um, e para ler uma posição sem aplicar nada, consulte aggrega serve.