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 вивести всі придатні до запуску приклади, які публікує документація, і нічого не записувати |
Що вона робить
Команда має дві форми. aggrega scaffold <kind> створює чернетку початкового документа за схемою виду й виводить її — саме це описують цей розділ і три наступні. aggrega scaffold --example <name> натомість записує один із придатних до запуску прикладів документації в новий каталог — див. Початок із придатного до запуску прикладу.
aggrega scaffold <kind> виводить у стандартний вивід початковий документ для одного виду сутності. Документ містить рівно ті поля, яких вимагає схема цього виду: 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 виводить увесь набір, а токен, якому не відповідає жодна схема, відхиляється з цим набором у повідомленні, тож друкарську помилку можна виправити без повторного пошуку.
Що вона повертає, а що ні
Документ походить із власного контракту виду і більше ні з чого. Це не готовий приклад. У ньому за вас не заповнено ні простору імен, ні категорії, ні значень міток, і немає закоментованих підказок про те, що зазвичай пишуть, — бо нічого з цього компілятор не вимагає. Каталог сам обирає своє іменування, свої категорії та свою структуру каталогів; поля визначає схема, і схема — це все, що читає ця команда. Початковий документ, який вгадував би решту, навчив би вас правила, якого не існує.
Створення чернетки не записує жодного файлу. Документ іде у стандартний вивід, тож місце, куди він потрапить, визначає перенаправлення, і нічого на диску не замінюється без вашого запиту:
aggrega scaffold component my-service > my-service.yamlЦе не завершена сутність, і саме це означає заповнювач. Порожнє обов’язкове значення не є значенням, тому запуск aggrega validate для документа в тому вигляді, у якому його виведено, відхиляє його й одразу називає кожен заповнювач, який ще потрібно заповнити, разом із тим, що він приймає, — вище це версія і тип компонента:
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. Їхня схема допускає порожній рядок, але порожній рядок не називає ні провайдера, ні типу, тому aggrega validate вказує обидва як ще не заповнені, доки ви їх не заповните. Таке тлумачення стосується лише перевірки одного файлу сутності: перевірка всього каталогу, aggrega validate --release і aggrega build його не застосовують. Що саме воно охоплює, див. у розділі заповнювачі, які ще потрібно заповнити. Створена сутність Recipe також не оголошує жодного з видів вхідних даних, принаймні один із яких вимагає її схема, — source, valuesMapping, workload чи artifacts, — бо вибір відповідного за вами, тож aggrega validate відхиляє її spec, доки ви не додасте один із них.
Той самий документ від асистента або редактора
Початковий документ складається з тих самих байтів, хоч би який інтерфейс його запитував. AI-асистент, під’єднаний через aggrega mcp, отримує його як інструмент scaffold, що повертає документ як текст разом із машинозчитуваними даними. Редактор, що працює з aggrega serve, отримує його через aggrega/scaffoldEntity. Документ виводиться зі схеми один раз, тож документ, який ви створюєте в терміналі, і документ, який створює для вас асистент, ідентичні байт у байт.
Запис і перелік готових до запуску прикладів доступні на тих самих поверхнях, а назвами полів слугують слова самої команди. Щоб записати приклад, надішліть інструменту scaffold або aggrega/scaffoldEntity поле example замість kind; dir — щоб назвати новий каталог відносно кореня робочого простору (якщо його не надіслано, це каталог із назвою прикладу там); а лише list: true — щоб отримати у відповідь усі приклади. Приклад читається з того самого пакета, перевіряється за тією самою політикою й записується тим самим розпакуванням, тож файли та наступні команди такі самі, як у терміналі, і відмови так само: каталог, що будь-що містить, запис, що веде за межі каталогу, або посилання, пакет, якого не приймає ваша політика, офлайн-робочий простір, у кеші якого нічого немає. Відповідь структурована: для переліку — examples, кожен із name, level і summary; для запису — example, dir, files — записані файли, відносно dir, — next, команди, які наводить сторінка прикладу, і version, версія документації, з якої прочитано приклад. Відповідь інструменту scaffold на запис також містить output_dir — розташування каталогу: через стандартні введення й виведення — повний шлях, щоб асистент, який назвав його відносно робочого простору, якого не бачить, прочитав, куди потрапив приклад, а через HTTP — відносно кореня робочого простору. Текст інструменту scaffold — це звіт, який друкує ця команда, завершений рядком, що називає це розташування там, де воно відрізняється від dir. Поля двох форм, надіслані разом, — скажімо, kind разом з example, — відхиляються однаковими словами на обох поверхнях, перш ніж щось буде прочитано. Редактор для форми прикладу називає робочий простір у полі workspaceRoot запиту, а dir має бути відносним шляхом, що залишається всередині нього й не веде за його межі через посилання; через HTTP інструмент так само обмежує dir робочим простором, який обслуговує, а через стандартні введення й виведення приймає dir так, як його названо, як і будь-який шлях. Індекс можливостей повідомляє про інструмент scaffold як про такий, що записує, через цю форму, а про cli-scaffold, який запускає цю команду в окремому процесі, — так само як про такий, що записує.
Початок із готового до запуску прикладу
Документація містить готові до запуску приклади — кожен із них є каталогом, що містить сутність Aggregate, її сутності Releases і все інше, з чого він збирається, разом зі сторінкою, яка пояснює, як його зібрати. --example записує один із них у новий каталог, тож можна почати з робочого проєкту, а не з порожнього:
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.Що записується і куди. Файли прикладу, як їх містить документація, записуються в каталог, який ви вказуєте другим аргументом, — або, якщо ви його не вказали, у каталог, названий за прикладом, у теці, в якій ви запускаєте команду. Каталог ще не повинен існувати або має бути порожнім. Усе інше відхиляється й залишається точно таким, яким було: каталог, що містить файл, файл за цим шляхом або посилання. Каталоги вище за нього, яких ще немає, створюються. Жоден файл прикладу не залишається деінде, і жоден не ставиться на місце, доки не записано всі: спершу їх записують окремо й переміщують, щойно всі вони на місці.
Команди, які вона друкує далі, — це ті, що наводить власна сторінка прикладу: перший блок sh, bash або shell під заголовком ## Build сторінки, як його записано на сторінці, разом із коментарями, після cd у цей каталог. Для прикладу, сторінка якого не має такого блоку, натомість повідомляється шлях до його сторінки.
Які приклади є. --list друкує кожен приклад, по одному разу, в порядку, в якому їх викладає документація, — його назву, рівень, який оголошує його сторінка, і перше речення його сторінки — і нічого не записує:
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 більше не читає, — скажімо, кандидат на випуск, запущений до публікації його власної документації, — команда відмовляє, повідомляючи про обидва факти одним реченням, і нічого не записується:
[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Його перевіряють перед використанням. Пакет завантажується з тими самими мережевими налаштуваннями, що й будь-яке інше читання з реєстру, а його підпис перевіряється за політикою підписів вашого робочого простору для цього реєстру, перш ніж пакет буде збережено, — і знову перед читанням копії, яка вже є на машині, тож копія, яку впустила м’якша політика іншого проєкту, не використовується за вашої. Пакет, якого ваша політика не приймає, відхиляється, і нічого не записується.
Його завантажують один раз на машину. Пакет зберігається в кеші, спільному для всіх проєктів Aggrega на машині, — див. aggrega cache, — тож другий приклад або другий проєкт не потребує повторного завантаження, а aggrega explain читає ту саму копію, коли обидва читають ту саму версію.
В офлайні читається лише те, що є в кеші. В офлайн-робочому просторі нічого не завантажується: приклад записується з копії, яка вже є на машині й яку допускає ваша політика, — тієї, що для цієї версії, або ж найновішої попередньої з кешу, — а якщо такої немає, команда відмовляє тією самою офлайн-відмовою, яку дає будь-яке мережеве читання, із зазначенням, як дозволити мережу.
Пакет, що містить щось неочікуване, відхиляється повністю. Пакет надходить із реєстру, тож розпакування нічого не довіряє в його структурі: запис, назва якого потрапила б за межі вказаного вами каталогу або за межі пакета, і запис, що є посиланням чи будь-чим іншим, крім файлу або каталогу, — кожен відхиляє весь приклад із зазначенням цього запису, і нічого не записується. Виконуваний файл у прикладі залишається виконуваним.
Читається конфігурація робочого простору. Типовий реєстр і політика підписів беруться з неї, тож файл конфігурації, що є посиланням, яке веде за межі робочого простору, зупиняє форму прикладу так само, як зупиняє будь-яку іншу команду, що читає конфігурацію, — див. межа робочого простору.
Приклади
Створити сутність Release без імені та переглянути її в терміналі:
aggrega scaffold releaseСтворити сутність Recipe одразу у файл:
aggrega scaffold recipe postgres-helm > postgres-helm.yamlПеревірити, що ще потрібно заповнити, перш ніж щось заповнювати:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlПерегляньте, які готові до запуску приклади є, а потім запишіть один із них у вибраний вами каталог:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cacheПро цикл створення, який починає ця команда, — створити форму, заповнити заповнювачі, перевірити, — див. Написання файлів Aggrega.