Огляд CLI
CLI aggrega — це точка входу компілятора. Кожна взаємодія з Aggrega — компіляція сутності Aggregate у придатні до розгортання артефакти, перегляд каталогу або IR, розв’язання та фіксація залежностей, публікація сутностей каталогу, перевірка коректності за допомогою validate, перевірка домовленостей щодо публікації за допомогою lint та обслуговування IDE — виконується через підкоманду aggrega. Цей набір розділів описує прапорці, вхідні та вихідні дані кожної підкоманди.
aggrega validate і aggrega lint — це взаємодоповнювальні засоби перевірки, що віддзеркалюють три області дії одне одного: увесь каталог, замикання залежностей сутності Release або одну сутність. aggrega validate перевіряє коректність (схему, стовпи, розв’язання посилань, extends, здатність провайдера щодо типів вхідних даних і — для сутності, що рендериться, — ізольований рендеринг); aggrega lint перевіряє домовленості щодо публікації (іменування, відповідність каталогів категоріям, префікси анотацій і розмір підвищення версії). Жодна з команд не створює артефактів; використовуйте validate, щоб відповісти на питання «чи це коректно?», і lint, щоб відповісти на питання «чи відповідає це дисципліні публікації каталогу?».
aggrega build дотримується принципу єдиної точки входу: сутність Release — єдиний вхід компіляції. aggrega build --release release.yaml зчитує вказівники aggregate: і manifest: сутності Release, щоб знайти решту топології, і створює вивід для кожної межі в dist/: іменована межа рендериться в оголошений нею directory: або в dist/boundaries/<boundary-name>/, якщо вона його не оголошує; сутність Release, що оголошує верхньорівневий components: замість іменованих меж, рендериться пласко в dist/. Кожен компонент, що міститься в топології, має належати одній із цих меж, а компонент, якого не містить жодна з них, зупиняє збірку: компонент потрапляє до межі або тому, що його названо в components: цієї межі під ідентифікатором, який він має після сплощення вкладених сутностей Aggregates, або тому, що він міститься у вкладеній сутності Aggregate, яку межа підключає через aggregates:. Компонент, що не потрапляє до межі жодним зі способів, рендерився б поза всіма межами, які оголошує Release, не отримуючи ні розташування виводу, ні хвилі синхронізації, ні анотацій, ні власного infra:, тож збірка зупиняється й називає цей компонент, а не створює артефакти, до яких конфігурацію меж сутності Release так і не було застосовано. Те саме відношення перевіряється і з боку Release: запис межі, що називає компонент, якого немає в топології, нічого не конфігурує, тому він також зупиняє збірку, а діагностика повідомляє ідентифікатор, до якого звертався запис. aggrega pull так само приймає Release як вхід; aggrega inspect приймає будь-яку сутність — ім’я в каталозі, файл сутності, посилання на реєстр або Release; aggrega push приймає сутність каталогу; aggrega validate і aggrega lint приймають сутність каталогу, сутність Release (через --release) або весь каталог; aggrega serve працює як довготривалий процес. На сторінці глобальних прапорців описано прапорці, що застосовуються до всіх підкоманд.
Що реліз може змінити в командах, прапорцях та інструментах асистента — і чого патч-реліз ніколи не змінює, — описано в розділі Сумісність.
Довідник за командами
aggrega build— основна команда компіляції. Читає вказівник на сутність Release, розв’язує сутності Aggregate і Manifest, на які він посилається, і видає скомпільовані артефакти для кожної межі.aggrega inspect— зручне для читання подання будь-якої сутності: сутності каталогу за ім’ям, файлу сутності за шляхом, опублікованої сутності, прочитаної безпосередньо з її реєстру, або повністю розв’язаної сутності Release, граф IR якої--ir-graphзаписує як JSON, а замикання залежностей якої виводить--closure.aggrega pull— розв’язати залежності сутності Release і записати lock-файл для цієї сутності Release, що фіксує кожну залежність; кешувати сутності каталогу та вихідні артефакти.aggrega push— опублікувати сутність каталогу в реєстрі OCI, за потреби підписавши її під час публікації.aggrega sign— підписати один або кілька вже опублікованих артефактів і приєднати кожен підпис як OCI referrer.aggrega auth token— інтерактивно отримати токен ідентичності OIDC і вивести його в stdout, щоб пройти автентифікацію один раз для пакета безключових підписувань.aggrega registry— керувати реєстрами, відомими робочому простору, і їхньою політикою довіри до підписів: додавати, переглядати й вилучати записи, а також створювати локальний індекс для пошуку опублікованих метаданих каталогу за допомогоюregistry update.aggrega search— шукати в локальному індексі налаштованих реєстрів опубліковані сутності каталогу та плагіни CLI, які можна встановити, за довільним текстовим запитом і необов’язковими фасетними фільтрами.aggrega validate— перевірити коректність (схему, опори, розв’язання посилань,extends, підтримку видів вхідних даних, ізольований рендеринг) для всього каталогу, замикання залежностей сутності Release (--release) або однієї сутності.aggrega lint— перевірити домовленості щодо публікації для всього каталогу, замикання залежностей сутності Release (--release) або однієї сутності;--pre-publishдодає перевірку зміни версії з урахуванням реєстру.aggrega serve— довготривалий демон «компілятор як сервіс» (JSON-RPC через stdin/stdout) для інтеграції з IDE.aggrega version— вивести версію CLI;-o jsonвидає машинозчитуваний об’єкт.aggrega get-schema— вивести канонічну JSON Schema для виду сутності або контракту;--listперелічує всі види. Це авторитетна форма, за якою слід створювати файл.aggrega scaffold— вивести початковий документ для виду сутності, побудований зі схеми цього виду: обов’язкові поля, де фіксовані заповнено, а скрізь, де потрібне значення, стоїть заповнювач. Під час створення чернетки файл не записується; перенаправте вивід куди потрібно. З--exampleкоманда натомість записує один із готових до запуску прикладів документації в новий каталог, а--example --listперелічує їх.aggrega mcp— запустити сервер Model Context Protocol через стандартні введення й виведення або через HTTP, щоб клієнт із підтримкою MCP став помічником зі створення, обізнаним з Aggrega. Див. Створення файлів Aggrega.aggrega skills— встановлює навичку, яка вчить AI-асистента встановлювати й використовувати Aggrega, у теку навичок цього асистента — для одного проєкту або, з--global, для всіх ваших проєктів.aggrega cache— перегляд і обслуговування кешів на диску: виведення їхнього вмісту, звільнення записів кешу артефактів, на які не посилається жоден lock-файл, скорочення кешу скомпільованих модулів до обмеження розміру або повне очищення всіх кешів.aggrega config— перегляд і керування конфігурацією, яку читає Aggrega: показ чинних налаштувань і того, який рівень визначив кожне з них, створення робочої конфігурації та фіксація критичних для збірки налаштувань у робочому просторі.aggrega deprecate— додавання підписаної позначки про застарілість до вже опублікованого артефакту.aggrega edit-document— застосування до документа одного обмеженого структурованого редагування зі збереженням кожного байта, якого воно не торкається.aggrega explain— пояснення умови зупинки, яку позначає код.aggrega import— перетворення стороннього опису джерела на чернеткові файли для створення в Aggrega.aggrega login— автентифікація в реєстрі OCI та збереження облікових даних, які пред’являютьpush,pullіlint --pre-publish.aggrega logout— видалення збережених облікових даних реєстру.aggrega pin— запис закріплень вмісту для зовнішніх вхідних даних сутності вentity.lockпоруч із нею.aggrega plugin— виведення списку плагінів Wasm, які може розв’язати CLI, додавання або видалення прив’язки робочого простору та перевірка гостьового модуля перед його публікацією.aggrega push-artifact— публікація самостійного артефакту даних, наприклад пакета документації, у реєстрі OCI в його просторі іменdocs/.- Конфігурація — у якому файлі має бути налаштування і як поєднуються рівні. Почніть звідси: розділ відкривається двома файлами, потрібними більшості проєктів, а механізми, до яких вдається більший проєкт, описує далі.
- Глобальні прапорці — прапорці, спільні для підкоманд (корінь робочого простору, глобальний файл конфігурації, кольоровий і простий доступний вивід та офлайн-режим). Офлайн-режим доступний також як налаштування конфігурації та змінна середовища — див. Конфігурація, схему конфігурації і змінні середовища.
- Межа робочого простору — що лежить усередині робочого простору, як символьне посилання, що веде за його межі, впливає на кожен вид шляху, які шляхи навмисно виходять назовні і що робити, коли такий шлях відхилено.
| Команда | Опис |
|---|---|
aggrega auth | Керувати ідентичністю для підписування |
aggrega build | Скомпілювати Aggregate і Release в артефакти, рідні для провайдера, у dist/ у корені робочого простору |
aggrega cache | Переглядати й обслуговувати кеші на диску |
aggrega config | Переглядати й керувати конфігурацією робочого простору |
aggrega deprecate | Приєднати підписану позначку застарілості до вже опублікованого артефакту |
aggrega edit-document | Застосувати до документа одне обмежене структуроване редагування, зберігши кожен байт, якого воно не торкається |
aggrega explain | Пояснити умову зупинки, яку позначає код |
aggrega get-schema | Вивести JSON Schema для виду сутності або контракту |
aggrega import | Перетворити сторонній опис джерела на чернетки файлів Aggrega |
aggrega inspect | Переглянути сутність каталогу за назвою, файл сутності за шляхом або опубліковану сутність за посиланням на реєстр |
aggrega lint | Перевірити домовленості щодо публікації в каталозі для всього каталогу, сутності Release або однієї сутності |
aggrega login | Автентифікуватися в реєстрі OCI і зберегти облікові дані |
aggrega logout | Вилучити збережені облікові дані реєстру |
aggrega mcp | Запустити сервер Model Context Protocol через стандартні введення й виведення або через HTTP для інтеграції з ШІ-помічниками |
aggrega pin | Записати фіксації вмісту для зовнішніх вхідних даних сутності в entity.lock поруч із нею |
aggrega plugin | Переглянути плагіни Wasm, які може розв’язати CLI |
aggrega pull | Розв’язати залежності каталогу й джерел у кеш і записати lock-файл для сутності Release |
aggrega push | Запакувати й опублікувати сутність каталогу в реєстрі OCI |
aggrega push-artifact | Опублікувати окремий артефакт даних (наприклад, пакет документації) в реєстрі OCI |
aggrega registry | Керувати реєстрами та їхньою політикою довіри до підписів |
aggrega scaffold | Створити початковий документ для виду сутності або записати готовий до запуску приклад у новий каталог |
aggrega search | Шукати в локальному індексі налаштованих реєстрів |
aggrega serve | Працювати як довготривалий «компілятор як сервіс» через JSON-RPC 2.0 на stdin/stdout |
aggrega sign | Підписати один або кілька вже опублікованих артефактів і приєднати їхні підписи |
aggrega skills | Встановити навичку Aggrega в AI-асистента |
aggrega validate | Перевірити коректність для всього каталогу, сутності Release або однієї сутності |
aggrega version | Вивести версію CLI aggrega |
Позиційні аргументи та код завершення
Кожна команда відхиляє позиційний аргумент, для якого в неї немає застосування, і повідомляє про це відхилення ненульовим кодом завершення, а не завершується так, ніби виклик був коректним. Правило охоплює й команди, які існують лише для групування підкоманд, де помилково введена назва підкоманди надходить як нерозпізнаний позиційний аргумент: виводиться довідка команди, а код завершення ненульовий, тож одруківка у скрипті призводить до явної помилки, а не виглядає як успішний запуск. aggrega, викликана з нерозпізнаною командою, поводиться так само й додатково називає найближчу відповідну команду, якщо така достатньо близька.
Нерозпізнана команда також підказує, як знайти плагін CLI з такою назвою. Відповідь береться з локального індексу типового реєстру, який будує aggrega registry update і читає aggrega search, тож вона повертається одразу, а помилково введене слово ніколи не надсилається до реєстру — ні онлайн, ні офлайн. Якщо індекс містить плагін CLI з такою назвою, повідомлення називає команду aggrega plugin add cli <name>, яка його встановлює. Якщо індекс не містить жодного, воно називає пошук, який його шукає, aggrega search <name> --kind plugin --plugin-type cli. Якщо індекс ще не побудовано, воно називає aggrega plugin add cli <name>, яка шукає плагін за цією назвою в реєстрі й відмовляє, якщо жодного не опубліковано. Будь-яка з цих команд містить назву, взяту в лапки для оболонки там, де це потрібно.
Там, де позиційні аргументи мають значення, власна довідкова сторінка кожної команди описує, що саме вона приймає. Установлений плагін CLI — навмисний виняток: його команда залишає розбір аргументів собі, тож увесь вектор аргументів передається плагіну, який є єдиним розбірником власних аргументів, — і виклик повертає власний код завершення плагіна.
Хід виконання і як довго команда чекає на реєстр
Команда, яка чекає, повідомляє, на що вона чекає. Щоразу, коли команда чекає на реєстр, на завантаження або на першу компіляцію плагіна, вона показує цей крок у стандартному потоці помилок, так само як aggrega build і aggrega pull показують свої: у терміналі — рядок із назвою кроку, анімованим індикатором і часом, який він уже зайняв, позначений галочкою після завершення кроку й залишений без галочки, якщо крок завершився невдало; у терміналі, який не може перемальовувати рядок на місці, або з --plain — по одному рядку на крок у момент його завершення, із його часом. Якщо стандартний потік помилок не є терміналом, нічого не показується, і те, що команда виводить у стандартний потік виводу, у жодному разі не змінюється. Крок показується лише доти, доки команда справді на нього чекає, тож запуск, обслужений із кешу, не показує нічого, а компіляція плагіна показується лише тоді, коли вона триває достатньо довго, щоб бути справжньою компіляцією, а не взятою з кешу.
Команди, які показують свої кроки в такий спосіб, крім команди кожного встановленого плагіна CLI:
aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate
Жоден запит не чекає на сервер безкінечно. Запит чекає щонайбільше 30 секунд, поки сервер почне відповідь після того, як запит надіслано повністю, і щонайбільше 30 секунд на наступну частину відповіді, яка вже надходить. Сервер, який змушує запит чекати довше, відхиляється з кодом E0376, що називає сервер і час очікування. Обмежено лише очікування: завантаження чи вивантаження, яке продовжує просуватися, триває стільки, скільки потрібно. Helm-чарт, який source: сутності Recipe отримує через HTTPS, підлягає лише першому з двох очікувань, а про його спливання повідомляється власними словами мережевої бібліотеки, а не під кодом E0376. Запит, який команда й так повторює в разі тайм-ауту, — читання під час aggrega registry update, запис під час публікації — повторюється до того, як буде повідомлено про відмову.
Обхід повного переліку репозиторіїв реєстру завершується протягом п’яти хвилин. Деякі реєстри збирають усі репозиторії, які вони містять, ще до того, як відповісти на запит переліку, тому на кожну сторінку переліку чекають стільки, скільки може тривати обхід, а не 30 секунд; перелік, який не завершився через п’ять хвилин, зупиняється й відхиляється з кодом E0377. aggrega plugin add обходить перелік лише тоді, коли жоден плагін не має точно тієї назви, яку йому передано, щоб знайти такий, назва якого її містить, тож якщо вказати точну назву плагіна, очікування на обхід ніколи не виникає.
На реєстр, який просить сповільнитися, команда чекає, доки він не проситиме про це п’ять хвилин без перерви. Команда чекає стільки, скільки просить такий реєстр, надсилає йому менше запитів одночасно й показує очікування разом з рештою свого прогресу; реєстр, який протягом п’яти хвилин не відповідає нічим, крім «сповільніться», відхиляється з кодом E0378. Як це відбувається, описано в розділі Реєстр, який просить сповільнитися.
Усі три обмеження фіксовані; немає жодного параметра, який би їх змінював.
Шляхи, які ви вводите, і межа робочого простору
Шлях, який ви вводите в командному рядку, — --release, --catalog, --output-dir, файл для перевірки, лінтингу, закріплення чи публікації, --workspace-root — використовується там, куди він веде, усередині робочого простору чи поза ним, через будь-яке посилання на шляху. Те, що команда потім читає й записує від власного імені, обмежено робочим простором, хоч би хто її запускав: вона не читає конфігураційних файлів робочого простору, документа каталогу, документа поруч із сутністю Release чи lock-файлу сутності Release через посилання, що веде за межі робочого простору, не переходить шляхом, який Release або Manifest виводить за його межі, і не записує свій вивід, свій lock-файл чи свій кеш через таке посилання. Каталог, який ви вказуєте поза робочим простором, обмежено так само щодо того, що лежить у ньому, а Release, яку ви вказуєте поза робочим простором, має доступ лише до файлів у власному каталозі. aggrega edit-document — єдина команда, введений шлях якої також обмежено: вона редагує лише документ, що міститься в робочому просторі. Межа робочого простору описує це правило, шляхи, що навмисно виходять за межі, і спосіб усунення кожної відмови.
Пошук в індексі каталогу
aggrega search [query] шукає опубліковані сутності в усіх реєстрах, відомих робочому простору. Необов’язковий [query] — це підрядок без урахування регістру, який зіставляється з назвою та описом кожної сутності. Фільтри за фасетами звужують набір результатів:
--kindобмежує пошук одним або кількома видами сутностей (component,feature,recipe,featurerecipe,workload,plugin); його можна повторювати, він не враховує регістр, а види поєднуються через АБО.-l/--selectorфільтрує за мітками каталогу сутності. Категорія — це мітка, а не окремий прапорець:-l component.aggrega.ai/category=datastore.--capabilityі--plugin-typeфільтрують плагіни за оголошеною можливістю або типом сокета;--capabilityможна повторювати, і значення поєднуються через АБО.--registryобмежує пошук одним реєстром за хостом або зручним псевдонімом; за замовчуванням пошук виконується в усіх налаштованих реєстрах.--limitобмежує кількість результатів.-o/--outputвибирає формат виводу:table(за замовчуванням, зручний для читання людиною),json(машинозчитуваний масив) абоnames(лише ідентифікатори, по одному в рядку).
Пошук завжди читає локальний індекс — офлайн-знімок, який створює та оновлює aggrega registry update. Він не звертається до мережі й нічого не завантажує на вимогу. Якщо індексу немає, команда завершується з помилкою й пропонує спершу виконати aggrega registry update. Кожен запуск виводить у стандартний потік помилок рядок актуальності «last updated» для кожного реєстру, тож вивід json і names у стандартному потоці виводу лишається чистим для скриптів.
Автодоповнення в оболонці
aggrega completion <shell> виводить у stdout скрипт автодоповнення для bash, zsh, fish або powershell. Скрипт генерується з актуального дерева команд CLI в момент запуску, тому він завжди відображає команди й прапорці того бінарного файлу, який його створив, — немає статичного файлу, який довелося б генерувати заново в міру розвитку CLI.
Щоб спробувати автодоповнення в поточному сеансі, нічого не встановлюючи, завантажте скрипт безпосередньо через source:
source <(aggrega completion bash)Щоб установити автодоповнення назавжди, запишіть скрипт у розташування, яке ваша оболонка зчитує під час запуску.
bash
Автодоповнення в Bash залежить від пакета bash-completion; установіть його через менеджер пакетів вашої ОС, якщо його ще немає.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
Якщо автодоповнення у вашій оболонці ще не ввімкнено, увімкніть його один раз:
echo "autoload -U compinit; compinit" >> ~/.zshrcПотім запишіть скрипт автодоповнення в каталог, що входить до вашого fpath:
# Linuxaggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggregafish
aggrega completion fish > ~/.config/fish/completions/aggrega.fishpowershell
Додайте згенерований скрипт у кінець свого профілю PowerShell, щоб він завантажувався в кожному сеансі:
aggrega completion powershell >> $PROFILEЗапустіть нову оболонку, щоб установлене автодоповнення набуло чинності.