コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

aggrega edit-document

文書に範囲を限定した構造化編集を 1 つ適用し、変更しないバイトはすべて保持します

概要

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

説明

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.

フラグ

フラグデフォルト説明
--dry-runfalse書き込み以外のすべてを行います。編集後の文書を、対象のファイル名を付けて内容として返し、何も作成も変更もしません。スキーマのゲートを含め、それ以外の動作はすべて書き込み時と同じです。指定しない場合は文書が書き込まれます
--name—新しいエントリを書き込むキー。コンポーネントのインスタンス名、アタッチメントの名前、接続のエイリアス、または値のキーです
--node[]文書のルートから、編集対象のノードに至る構造パスの 1 セグメント。セグメントごとに 1 回ずつ、外側から順に繰り返し指定します。ドット区切りの 1 つのパスではなくセグメント単位で受け取るのは、入力する名前にドットを含めてよいためで、連結したパスでは誰も書いていないキーを指してしまう可能性があるからです
--socket—接続を配線する依存関係のソケット。wire-edge の場合に読み取られ、それ以外では無視されます
--value—エントリが持つ内容で、YAML スカラーとして読み取られます。その意味は編集によって決まります。エントリが要求するエンティティ、接続が指すノード、または値に設定するスカラーです

動作

aggrega edit-document <edit> <file> は、ワークスペース内の文書に構造化編集を 1 つ適用し、変更しなかったバイトはすべて記述したとおりに残します。編集を先に、文書を後に指定します:

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

このコマンドは、編集箇所を教えてもらうよりもファイルを直接編集してほしい場合のためにあります。独自のバッファと独自の取り消し履歴を持っている場合は、aggrega serve が位置を報告し、テキストの配置は自分で行えます。このコマンドはエントリを組み立てて書き込みます。

文書はワークスペースが保持するものです。 ワークスペースのルートからの相対パスまたは絶対パスで指定します。ワークスペース外の文書は、何も読み書きせずに拒否されます。そのように記述された場合も、ワークスペース外へ通じるリンク (ファイルへのリンク、または途中のディレクトリがリンクである場合) を経由した場合も同様です。編集は文書を書き戻す前に読み込むため、そのようなリンクの先にある文書はワークスペースが保持しないファイルであり、拒否のメッセージにもそう示されます:

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"

別の場所にある文書を編集するには、その文書を保持するワークスペースでコマンドを実行します。言語サーバーとアシスタントツールによる編集にも同じ規則が適用されます。3 つとも同一の編集を適用するためです。その文書は、入力するパスのうちワークスペース内に限定される唯一のパスです。詳しくは ワークスペースの境界 を参照してください。

1 回の呼び出しで 1 つのエントリ、そして編集の集合は閉じている

編集は 4 つあり、それ以外はありません。

編集追加するもの
add-componentcomponents コンテナの下のコンポーネントインスタンス
attach-feature指定したノード上の Feature アタッチメント
wire-edgeそのノードの依存ソケットの 1 つの中の接続
set-value指定したノード上の 1 つの値

削除する編集、既に書いたブロックを置き換える編集、何かを並べ替える編集、指定したバイト列をそのまま書き込む編集はありません。 これは設計に対する制限ではなく、設計そのものです。4 つ以外の名前はこのコマンドを通る経路をまったく持たないため、これは名前を狭めただけのファイル書き込みツールではありません。集合の外の名前は解釈されずに拒否されます。

要求した内容を持つエントリが既に存在する場合は何もしません。コマンドはその旨を伝え、何も書き込みません。

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

その名前のエントリが別の内容を持っている場合は、置き換えられずに拒否されます。書いたものを置き換えることは 4 つの編集のいずれでもないためです。

ノードはパスとして、1 セグメントずつ指定します

--node は、ドキュメントのルートからのパスのセグメントごとに 1 回ずつ、外側から順に繰り返して指定します。

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

ドット区切りの 1 つのパスではなく 1 セグメントずつ受け取るのは意図的であり、その理由は正しさに関わるものです。 ドットは入力する名前の中で使える正当な文字であるため、ドキュメントの外からは、構造上のドットと名前の中のドットを区別できません。連結したパスは正しく読めても、誰も書いていないキーを指してしまいます。さらに add-component はドキュメントにないコンテナを作成することがあるため、エントリは拒否されずに、その架空のキーの下に置かれてしまいます。セグメントは曖昧さを別の場所に移すのではなく、取り除きます。

add-component の場合、追加されるエントリ自体がノードであるため、パスは components コンテナそのものを指定します。他の 3 つの場合、パスは編集の対象となるノードを指定し、コンテナは編集の種類から決まります。アタッチメントはそのノードの features の下に、接続はその uses と指定したソケットの下に、値はその values の下に置かれます。

--name は、エントリが書き込まれるキーです。つまり、インスタンス名、アタッチメントの名前、接続のエイリアス、または値のキーです。--socket は wire-edge の場合に読み取られ、それ以外では無視されます。

値は、その文字が表す型を保ちます

--value は YAML スカラーとして読み取られます。これは、その文字をドキュメントに直接入力した場合と同じ読み取り方です。

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

したがって、--value 4 は数値を、--value true は真偽値を、--value '"4"' は文字列 4 を設定します。ここでの引用符は、ドキュメント内とまったく同じく「これはテキストである」ことを示します。--value を省略すると、何も設定されません。マッピングやシーケンスは拒否されます。それを書き込むことはブロックの追加にあたり、4 つの編集のいずれにも該当しないためです。

編集しなかった部分はすべて残り、同じリクエストは同じバイト列を生成する

ドキュメントは、コンテナとそのブロックが終わる行を特定するためだけに解析されます。エントリはレンダリングされ、行単位で挿入されます。コメント、空行、クォートのスタイル、折り畳みスカラーとリテラルスカラー、テンプレート式、末尾の改行の形はすべてそのまま引き継がれます。また、ネストの段差は押し付けられるのではなく、ドキュメント自身のインデントから測定されます。そのため、エントリはすでに書いているスタイルのまま配置されます。

同じドキュメントと同じリクエストを与えれば、バイト列は毎回同じになります。そのため 2 回の実行結果を比較でき、レビューでは 1 つの編集が 1 つの差分として読めます。

結果は手で入力できたはずのドキュメントでなければならない

書き込みはこの条件で制御されます。 組み立てられたドキュメントは、そのドキュメント自身の kind のスキーマに照らして検査されます。スキーマは利用者が指定するのではなくドキュメントから読み取られ、検査に合格した場合にのみバイト列がディスクに書き込まれます。スキーマが拒否するものを生成することになるリクエストは拒否され、スキーマが受け付けないプロパティとその場所が示されます。

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"

ファイルはバイト単位で元のまま残され、書き込み自体もアトミックです。そのため、拒否された編集や中断された編集は一度も試みられなかった編集と区別がつかず、修正したリクエストを元のドキュメントに対して再試行できます。ここでオーサリングの規則を改めて述べないのもこのためです。Release ドキュメントに開発者向けの値を持たせるよう求めるリクエストは、手で入力したドキュメントを拒否するのと同じスキーマによって拒否されます。

何が意味的に許容されるかは、ここでは判定しません。 依存ソケットがプロデューサーの宣言したものかどうか、また Feature の適用条件が満たされているかどうかは、ビルドが行う解決の役割です。そのため、このコマンドが把握していない接続を指定することもでき、Aggregate はカタログエンティティが事前に宣言していないソケットを記述することもできます。ソケットを介して何を消費できるかを宣言するのは、引き続きプロデューサーの役割です。それを確かめたい場合は、Release を指定して aggrega validate を実行してください。

保存する前に結果を確認する

--dry-run は、書き込み以外のすべてを通常のコマンドと同じように行います。編集されたドキュメントは、対象のファイル名を示したうえで内容として標準出力に出力され、何も作成されません。

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

指定しない場合、ドキュメントは書き込まれます。 このコマンドの成果物は編集されたドキュメントであり、それを生成するコマンドはその成果物を届ける責任を負うため、デフォルトは書き込みです。出力先について何も指定しないリクエストは、ファイルを編集します。

それ以外の動作はすべて書き込み時と同じです。検証ゲートも含まれます。結果がスキーマに拒否される編集は --dry-run でも拒否され、同じプロパティを示し、ファイルはまったく元のまま残ります。そのため、ドライランで得られる終了コードは、書き込みを行った場合に得られる終了コードと同じです。

エディタやアシスタントからの同じ編集

どのサーフェスが編集を適用しても、バイト列は同じです。aggrega serve を操作するエディタは aggrega/editDocument でこれに到達し、aggrega mcp を通じて接続された AI アシスタントは、このコマンドがそこで公開されているツールとしてこれに到達します。エントリの構成、差し込み、検証によるゲートは一か所で行われ、各サーフェスはそこへの薄いエントリポイントにすぎません。そのため、ターミナルで編集したドキュメントと、エディタが代わりに編集したドキュメントはバイト単位で同一になります。

サーフェス間で唯一異なるのは、どのバイト列を読むかです。このコマンドとセッションメソッドはどちらもディスク上のファイルを読み、未保存のバッファは決して読みません。バッファから書き込むと、1 つのエントリを適用するという名目で、保存していない内容がページに書き込まれてしまうためです。まず保存してから編集してください。

例

Aggregate のトップレベルにコンポーネントインスタンスを追加します:

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

サブシステム内で記述されたコンポーネントに Feature をアタッチします:

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

サブシステム内で記述されたコンポーネントに値を設定します:

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

何かが書き込まれる前に結果を確認します:

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

コンテナを指定する前にエントリがどのコンテナに属するかを調べる方法、および何も適用せずに位置を読み取る方法については、aggrega serve を参照してください。