Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

aggrega edit-document

Aplicar uma edição estruturada delimitada a um documento, preservando todos os bytes em que 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

FlagPredefiniçãoDescrição
--dry-runfalseFazer tudo exceto escrever: devolver o documento editado como conteúdo, nomeando o ficheiro a que se destina, e não criar nem modificar nada. Todo o restante comportamento é o da escrita, incluindo o controlo do esquema. Sem ela, o documento é escrito
--name—A chave sob a qual a nova entrada é escrita: o nome da instância do componente, o nome da anexação, o alias da ligação ou a chave do valor
--node[]Um segmento do caminho estrutural, a partir da raiz do documento, até ao nó a que a edição diz respeito. Repita-a uma vez por segmento, do mais exterior para o mais interior. Aceita um segmento de cada vez em vez de um único caminho com pontos porque um ponto é um carácter válido num nome escrito pelo utilizador, pelo que um caminho unido poderia endereçar uma chave que ninguém escreveu
--socket—O socket de dependência dentro do qual uma ligação é estabelecida. Lido para wire-edge e ignorado nos outros casos
--value—O que a entrada contém, lido como escalar YAML. O seu significado decorre da edição: a entidade que a entrada pede, o nó para o qual uma ligação aponta ou o escalar com que um valor é definido

O que faz

aggrega edit-document <edit> <file> aplica uma edição estruturada a um documento do espaço de trabalho e deixa cada byte em que não tocou exatamente como foi escrito. A edição é nomeada primeiro e o documento em segundo lugar:

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

Existe para os casos em que se prefere que o ficheiro seja editado a ser informado de onde o editar. Se mantiver o seu próprio buffer e o seu próprio histórico de anulação, aggrega serve reporta uma posição e permite colocar o texto por conta própria; este compõe a entrada e escreve-a.

O documento é um que o espaço de trabalho contém. Nomeie-o em relação à raiz do espaço de trabalho ou pelo seu caminho absoluto; um que esteja fora do espaço de trabalho é recusado sem nada lido nem escrito, quer esteja escrito dessa forma quer seja alcançado através de uma ligação que sai do espaço de trabalho — uma ligação para o ficheiro, ou um diretório pelo caminho que seja uma ligação. Uma edição lê o documento antes de o voltar a escrever, pelo que um documento por detrás de uma ligação dessas é um ficheiro que o espaço de trabalho não contém, e a recusa indica-o:

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 guardado noutro local, execute o comando no espaço de trabalho que o contém. As edições do servidor de linguagem e das ferramentas do assistente aplicam a mesma regra, porque os três aplicam uma única edição. O seu documento é o único caminho escrito pelo utilizador que está sujeito ao espaço de trabalho, como estabelece A fronteira do espaço de trabalho.

Uma chamada, uma entrada, e o conjunto é fechado

Há quatro edições e nenhuma outra:

EdiçãoO que acrescenta
add-componentuma instância de componente sob um contentor de componentes
attach-featureuma anexação de Feature no nó nomeado
wire-edgeuma ligação dentro de um dos sockets de dependência desse nó
set-valueum valor no nó nomeado

Não há nenhuma edição que elimine, substitua um bloco já escrito, reordene algo ou escreva literalmente bytes fornecidos pelo utilizador. Este é o desenho completo e não uma restrição sobre ele: um nome fora dos quatro não tem nenhum caminho através do comando, pelo que este não é um escritor de ficheiros com um nome mais restrito. Um nome fora do conjunto é recusado em vez de interpretado.

Uma entrada que já existe, contendo o que foi pedido, é uma operação nula — o comando indica-o e não escreve nada:

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

Uma entrada com esse nome que contenha outra coisa é recusada em vez de substituída, porque substituir o que foi escrito não é uma das quatro.

O nó é nomeado como um caminho, um segmento de cada vez

--node é repetido uma vez por segmento do caminho a partir da raiz do documento, do mais exterior para o mais interior:

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

Aceita um segmento de cada vez em vez de um único caminho com pontos de propósito, e a razão é de correção. Um ponto é um carácter válido num nome escrito pelo utilizador, pelo que nada fora do documento consegue distinguir um ponto estrutural de um que esteja 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 contentor que o documento não contém, a entrada ficaria sob essa chave inventada em vez de ser recusada. Os segmentos eliminam a ambiguidade em vez de a deslocar.

Para add-component, o caminho nomeia o próprio contentor de componentes, porque a entrada que é acrescentada é o nó. Para as outras três, nomeia o nó a que a edição diz respeito, e o contentor decorre da edição: uma anexação vai para os features desse nó, uma ligação para os seus uses e o socket nomeado, um valor para os seus values.

--name é a chave sob a qual a entrada é escrita — o nome da instância, o nome da anexação, o alias da ligação ou a chave do valor. --socket é lido para wire-edge e ignorado nos outros casos.

Um valor mantém o tipo que os seus caracteres transmitem

--value é lido como escalar YAML, que é a mesma forma como os caracteres seriam lidos se tivessem sido escritos no documento:

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

Assim, --value 4 define um número, --value true um booleano e --value '"4"' a cadeia 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 escrever um seria acrescentar um bloco, e isso não é uma das quatro edições.

Tudo o que não foi editado sobrevive, e o mesmo pedido produz os mesmos bytes

O documento só é analisado para localizar o contentor e a linha em que o seu bloco termina; a entrada é renderizada e inserida ao nível da linha. Os comentários, as linhas em branco, o estilo de aspas, os escalares dobrados e literais, as expressões de template e a forma da quebra de linha final passam todos inalterados, e o passo de aninhamento é medido a partir da própria indentação do documento em vez de imposto — pelo que uma entrada fica no estilo em que já se está a escrever.

Dado o mesmo documento e o mesmo pedido, os bytes são sempre os mesmos. Assim, é possível comparar duas execuções, e uma revisão lê uma edição como um diff.

O resultado tem de ser um documento que poderia ter sido escrito à mão

É disso que a escrita depende. O documento composto é verificado contra o esquema do seu próprio tipo, lido a partir do documento e não fornecido pelo utilizador, e os bytes só chegam ao disco se essa verificação passar. Um pedido que produziria algo que o esquema recusa é recusado, nomeando a propriedade que o esquema não admitiria e onde:

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"

O ficheiro fica byte a byte como estava, e a própria escrita é atómica, pelo que uma edição recusada ou interrompida é indistinguível de uma que nunca foi tentada, e é possível repetir um pedido corrigido sobre o documento inicial. É também por isso que nenhuma regra de autoria é aqui repetida: pedir a um documento de Release que contenha um valor de programador é recusado pelo mesmo esquema que recusaria o documento escrito à 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 uma compilação efetua. Assim, é possível nomear uma ligação de que este comando nunca ouviu falar, e um Aggregate pode escrever um socket que a sua entidade de catálogo não declara previamente; o que pode ser consumido através de um socket continua a caber ao produtor declarar. Execute aggrega validate nomeando uma Release quando for essa a questão.

Ver o resultado antes de ser guardado

--dry-run faz tudo o que o comando simples faz exceto escrever: o documento editado vai para a saída padrão como conteúdo, nomeando o ficheiro a que se destina, e nada é criado:

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.
...

Sem ela, o documento é escrito. A predefinição é a escrita, porque o produto deste comando é um documento editado e um comando que produz um deve entregá-lo — um pedido que nada diz sobre a entrega edita o ficheiro.

Todo o restante comportamento é o da escrita, incluindo o controlo de validação. Uma edição cujo resultado o esquema recusaria é também recusada com --dry-run, nomeando a mesma propriedade e deixando o ficheiro exatamente como estava — pelo que o código de saída de uma execução de teste é o código de saída que a escrita teria dado.

A mesma edição a partir de um editor ou de um assistente

Os bytes são os mesmos seja qual for a superfície que aplica a edição. Um editor que conduz aggrega serve chega a ela em aggrega/editDocument, e um assistente de IA ligado através de aggrega mcp chega a ela como a ferramenta com que este comando aí é exposto. A entrada é composta, inserida e sujeita a validação num único local, e cada superfície é um ponto de entrada fino para ele — pelo que o documento editado num terminal e o documento que um editor edita pelo utilizador são idênticos byte a byte.

O único aspeto em que as superfícies diferem é nos bytes que leem. Este comando e o método de sessão leem ambos o ficheiro em disco, nunca um buffer não guardado: escrever a partir de um buffer colocaria na página conteúdo que não foi guardado, sob a aparência de aplicar uma entrada. Guarde primeiro e depois edite.

Exemplos

Acrescentar uma instância de componente no nível superior de um Aggregate:

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

Anexar uma Feature a um componente escrito dentro de um subsistema:

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

Definir um valor num componente escrito dentro de um subsistema:

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

Rever o resultado antes de algo ser escrito:

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

Para saber a que contentor pertence uma entrada antes de nomear um, e para ler uma posição sem aplicar nada, consulte aggrega serve.