aggrega scaffold
エンティティ種別のスターター文書の草案を作成するか、実行可能な例を新しいディレクトリに書き出します
概要
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]説明
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.フラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--example | false | 引数が指定する実行可能な例を、署名付きドキュメントバンドルから読み取って新しいディレクトリに書き出します |
--list | false | —example と併用すると、ドキュメントが公開しているすべての実行可能な例を表示し、何も書き込みません |
動作
このコマンドには 2 つの形式があります。aggrega scaffold <kind> は kind のスキーマからスターター文書を作成して出力します。この節と続く 3 つの節ではこちらを説明します。aggrega scaffold --example <name> は代わりに、ドキュメントの実行可能な例の 1 つを新しいディレクトリに書き出します。実行可能な例から始めるを参照してください。
aggrega scaffold <kind> は、1 つのエンティティ種別のスターター文書を標準出力に出力します。この文書には、その種別のスキーマが必須とするフィールドだけが含まれます。apiVersion と kind はスキーマが固定しているため値が入っており、それ以外の必須の値はすべて、置き換えるためのプレースホルダーとして残されます。
省略可能な [name] は、スキーマが metadata.name を必須とする種別について、その初期値を与えます。
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}種別は、小文字をハイフンでつないだスキーマトークンです。component、aggregate、release、recipe、manifest、feature などがあります。aggrega get-schema --list はその一覧全体を出力します。どのスキーマにも対応しないトークンは拒否され、メッセージにその一覧が含まれるため、入力ミスは改めて調べることなく修正できます。
返すものと返さないもの
文書は、その種別自身の契約だけから作られます。 これは実例ではありません。namespace、カテゴリ、ラベルの値はどれも入力されず、よく書かれる内容をコメントで提案することもありません。いずれもコンパイラが必須とするものではないためです。カタログは独自の命名、独自のカテゴリ、独自のディレクトリ構成を選びます。フィールドを決めるのはスキーマであり、このコマンドが読むのはスキーマだけです。残りを推測したスターター文書は、存在しない規則を教えてしまうことになります。
下書きの作成ではファイルは書き込みません。 文書は標準出力に出力されるため、出力先はリダイレクトで決まり、求めない限りディスク上のものが置き換えられることはありません:
aggrega scaffold component my-service > my-service.yamlこれは完成したエンティティではなく、それこそがプレースホルダーの意味です。 空の必須値は値ではないため、出力されたままの文書に対して aggrega validate を実行すると文書は拒否され、まだ必要なプレースホルダーがすべて一度に、それぞれが受け付ける内容とともに示されます。上の例では、バージョンと component type です。
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, resource各値が受け付ける内容は、その種別自身のスキーマから読み取られます。スキーマが列挙している場合は受け付ける値、スキーマが求める場合はセマンティックバージョン、それ以外の場合はそのフィールドに対するスキーマ自身の説明です。これらの値を与えれば、同じコマンドが文書を受け入れます。形はスキーマから作られたものなので、形を変える必要はまったくありません。
スキーマが空を受け付ける場合でも、値は必要です。 草案として作成された Recipe または FeatureRecipe では、capability と implements が空になっています。スキーマは空文字列を許しますが、空ではどの provider も type も指定しないため、aggrega validate は値が入力されるまで両方をまだ必要なものとして示します。この解釈は 1 つのエンティティファイルの検証にのみ適用されます。カタログ全体の実行、aggrega validate --release、aggrega build には適用されません。対象範囲についてはまだ必要なプレースホルダーを参照してください。また、草案の Recipe は、スキーマが少なくとも 1 つを求める入力種別(source、valuesMapping、workload、artifacts)をどれも宣言していません。どれが適するかは作成者が選ぶものだからです。そのため、1 つ追加するまで aggrega validate はその spec を拒否します。
アシスタントやエディタから得られる同じ文書
スターター文書は、どのインターフェースから要求しても同じバイト列です。aggrega mcp 経由で接続した AI アシスタントは scaffold ツールとしてこれを利用でき、このツールは文書をテキストとして、機械可読なペイロードとともに返します。aggrega serve を利用するエディタは aggrega/scaffoldEntity でこれを利用できます。文書はスキーマから一度だけ導出されるため、ターミナルで作成した草案とアシスタントが作成した草案はバイト単位で同一です。
実行可能なサンプルの書き出しと一覧表示も同じインターフェースで提供され、フィールド名にはこのコマンド自身の用語が使われます。scaffold ツールまたは aggrega/scaffoldEntity に、kind の代わりに example を送るとサンプルを 1 つ書き出し、dir を送ると新しいディレクトリをワークスペースルートからの相対パスで指定します(送らない場合は、そこにサンプル名のディレクトリが使われます)。list: true だけを送ると、すべてのサンプルが返されます。サンプルは同じバンドルから読み込まれ、同じポリシーで検証され、同じ展開処理で書き出されるため、書き出されるファイルと次に実行するコマンドはターミナルの場合と同じであり、拒否される場合も同じです。つまり、何かを含むディレクトリ、ディレクトリの外へ出るエントリまたはリンク、ポリシーが受け入れないバンドル、何もキャッシュされていないオフラインのワークスペースです。回答は構造化されています。一覧の場合は examples で、各要素は name、level、summary を持ちます。書き出しの場合は example、dir、files(書き出されたファイルで、dir からの相対パス)、next(サンプルのページが示すコマンド)、version(サンプルを読み込んだドキュメントのバージョン)です。書き出しに対する scaffold ツールの回答には、ディレクトリの場所を示す output_dir も含まれます。標準入出力経由では完全なパスで示されるため、見ることのできないワークスペースからの相対パスで指定したアシスタントでも、サンプルの書き出し先がわかります。HTTP 経由ではワークスペースルートからの相対パスです。scaffold ツールのテキストは、このコマンドが出力する説明であり、その場所が dir と異なる場合は、その場所を示す行で締めくくられます。2 つの形式のフィールドを一緒に送ると(たとえば kind と example)、何かを読み込む前に、どちらでも同じ文言で拒否されます。エディターはサンプル形式ではリクエストの workspaceRoot でワークスペースを指定し、dir はその内部にとどまり、リンクを経由して外に出ない相対パスでなければなりません。HTTP 経由では、ツールは dir を提供先のワークスペース内に限定し、標準入出力経由では、他のすべてのパスと同様に dir を指定どおりに受け取ります。機能インデックスは、この形式があるため scaffold ツールを書き込みを行うものとして報告し、このコマンドを別プロセスで実行する cli-scaffold も同じく書き込みを行うものとして報告します。
実行可能なサンプルから始める
ドキュメントには実行可能なサンプルが含まれています。各サンプルは、Aggregate、その Releases、およびビルドの元になるその他のものを含むディレクトリで、ビルド方法を説明するページが付いています。--example はそのうちの 1 つを新しいディレクトリに書き出すため、空のプロジェクトではなく動作するプロジェクトから始められます:
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.何を、どこに書き出すか。 サンプルのファイルを、ドキュメントに含まれているとおりに、2 番目の引数で指定したディレクトリに書き出します。指定しない場合は、コマンドを実行したフォルダー内の、サンプル名を付けたディレクトリに書き出します。ディレクトリはまだ存在しないか、空でなければなりません。それ以外の場合は拒否され、元のまま残されます。つまり、ファイルを含むディレクトリ、そのパスにあるファイル、またはリンクです。まだ存在しない上位のディレクトリは作成されます。サンプルのファイルが他の場所に残されることはなく、すべてが書き出されるまでどれも所定の場所には置かれません。まず別の場所に書き出され、すべてがそろった時点で移動されます。
次に出力されるコマンドは、サンプル自身のページが示すものです。ページの ## Build 見出しの下にある最初の sh、bash、または shell ブロックを、コメントも含めページに書かれているとおりに、ディレクトリへの cd の後に出力します。そのようなブロックがないページのサンプルでは、代わりにそのページのパスが返されます。
どのサンプルがあるか。 --list はすべてのサンプルをドキュメントが教える順序で 1 回ずつ出力し(名前、ページが宣言するレベル、ページの最初の文)、何も書き出しません:
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....この一覧はドキュメント自身のサンプル一覧で、サンプルとともに製品と機能別のサンプルとして公開されているものです。バンドルにサンプルがない名前は、--list を案内して拒否され、何も書き出されません。
サンプルの入手元。 サンプルはドキュメントバンドルから読み込まれます。これは公開されたドキュメントの署名付きアーカイブで、aggrega explain が解説を読み込むのと同じものであり、ワークスペースのデフォルトレジストリで公開されています。読み込まれるバンドルは、実行中の aggrega のバージョン向けに公開されたものです。そのバージョン向けに公開されたものがない場合は、それより前のリリース向けに公開された最新のものが読み込まれ、コマンドはその旨を標準エラーに出力します:
note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before itリリース後のいくつかのコミットからビルドされた aggrega(aggrega version が 0.9.0-12-g1a2b3c4d のように表示されるもの)は、ビルドの基になったリリース(ここでは 0.9.0)のドキュメントを読み込み、それが公開されていない場合はそれより前のものを読み込みます。リリース候補などのプレリリース後のいくつかのコミットからビルドされたもの(aggrega version が 0.9.0-rc.6-4-gc9db2f597 のように表示されるもの)は、そのプレリリース(ここでは 0.9.0-rc.6)のドキュメントを読み込み、それが公開されていない場合は、それより前に公開された最新のもの(以前のプレリリースを含む)を読み込みます。それ以外のビルドがプレリリースのドキュメントを読み込むのは、そのビルド自体がそのプレリリースである場合だけです。リリース番号が付与されていないビルドは、自身のバージョンのドキュメントを読み込むか、何も読み込みません。aggrega explain も、ウォークスルーを読み込むバンドルを同じ方法で選択します。
使用しているバージョン向けに公開されたものがなく、それより前の最新のものがこのバージョンの aggrega ではもう読み込めない形式である場合 — たとえば、自身のドキュメントが公開される前に実行したリリース候補版など — コマンドはその両方を 1 文で示して拒否し、何も書き込みません:
[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 read使用前に検証されます。 バンドルは他のすべてのレジストリ読み込みと同じネットワーク設定で取得され、保持される前に、そのレジストリに対するワークスペースの署名ポリシーで署名が確認されます。マシン上にすでにあるコピーを読み込む前にも再度確認されるため、別のプロジェクトのより緩いポリシーで取り込まれたコピーが、このワークスペースのポリシーの下で使われることはありません。ポリシーが受け入れないバンドルは拒否され、何も書き出されません。
取得はマシンごとに 1 回です。 バンドルは、マシン上のすべての Aggrega プロジェクトが共有するキャッシュに保持されます(aggrega cache を参照)。そのため、2 つ目のサンプルや 2 つ目のプロジェクトで再度ダウンロードする必要はなく、両者が同じバージョンを読み込む場合、aggrega explain も同じコピーを読み込みます。
オフラインでは、キャッシュされたものだけを読み込みます。 オフラインのワークスペースでは何も取得されません。サンプルは、マシン上にすでにあり、ポリシーが認めるコピー(このバージョン向けのもの、なければキャッシュされているそれより前の最新のもの)から書き出されます。コピーがない場合、コマンドはすべてのネットワーク読み込みが返すオフラインの拒否で拒否し、ネットワークを許可する方法を示します。
想定外のものを含むバンドルは全体が拒否されます。 バンドルはレジストリから取得されるため、展開処理はそのレイアウトについて何も信頼しません。名前が指定したディレクトリの外やバンドルの外に出るエントリ、およびリンクであるエントリやファイルでもディレクトリでもないエントリは、いずれもそのエントリを示してサンプル全体を拒否し、何も書き出されません。サンプル内の実行可能ファイルは実行可能なまま残ります。
ワークスペースの設定が読み込まれます。 デフォルトレジストリと署名ポリシーはそこから取得されるため、ワークスペースの外へ通じるリンクである設定ファイルは、設定を読み込む他のすべてのコマンドと同様に、サンプル形式も停止させます。ワークスペースの境界を参照してください。
例
名前のない Release の草案を作成し、ターミナルで確認します。
aggrega scaffold releaseRecipe の草案を直接ファイルに作成します。
aggrega scaffold recipe postgres-helm > postgres-helm.yaml何かを入力する前に、まだ必要なものを確認します。
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlどの実行可能なサンプルがあるかを確認し、そのうちの 1 つを任意のディレクトリに書き出します:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cacheこのコマンドで始まるオーサリングの流れ(形の草案を作成し、プレースホルダーを埋め、検証する)については、Aggrega ファイルの作成を参照してください。