Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Ikhtisar CLI

CLI aggrega adalah titik masuk compiler. Setiap interaksi dengan Aggrega — mengompilasi Aggregate menjadi artefak yang dapat di-deploy, memeriksa katalog atau IR, meresolusikan dan menyematkan dependensi, memublikasikan entitas katalog, memeriksa kebenaran dengan validate, memeriksa konvensi publikasi dengan lint, dan melayani IDE — berjalan melalui subperintah aggrega. Kumpulan bab ini membahas flag, input, dan output setiap subperintah.

aggrega validate dan aggrega lint adalah pemeriksa yang saling melengkapi dan mencerminkan tiga cakupan satu sama lain — seluruh katalog, closure dependensi sebuah Release, atau satu entitas. aggrega validate memeriksa kebenaran (skema, pilar, resolusi referensi, extends, kapabilitas jenis input provider, dan — untuk entitas yang merender — render terisolasi); aggrega lint memeriksa konvensi publikasi (penamaan, keselarasan direktori kategori, prefiks anotasi, dan besarnya kenaikan versi). Keduanya tidak menghasilkan artefak; gunakan validate untuk menjawab “apakah ini benar?” dan lint untuk menjawab “apakah ini mengikuti disiplin publikasi katalog?”.

aggrega build mengikuti Prinsip Titik Masuk Tunggal: Release adalah satu-satunya input kompilasi. aggrega build --release release.yaml membaca penunjuk aggregate: dan manifest: milik Release untuk menemukan sisa topologi, dan menghasilkan output per batas di bawah dist/: batas bernama dirender di bawah directory: yang dideklarasikannya, atau di bawah dist/boundaries/<boundary-name>/ jika tidak mendeklarasikannya; Release yang mendeklarasikan components: tingkat atas alih-alih batas bernama dirender secara datar di bawah dist/. Setiap komponen dalam topologi harus menjadi bagian dari salah satu batas tersebut, dan komponen yang tidak dimuat batas mana pun menghentikan build: komponen mencapai sebuah batas dengan disebut di bawah components: batas tersebut, dengan id yang dibawanya setelah sub-Aggregates diratakan, atau dengan berada di dalam sub-Aggregate yang dirutekan batas tersebut di bawah aggregates:. Komponen yang tidak mencapai keduanya akan dirender di luar setiap batas yang dideklarasikan Release, tanpa sumber apa pun untuk lokasi output, sync wave, anotasi, dan infra: per komponennya, sehingga build berhenti dan menyebut komponen tersebut alih-alih menghasilkan artefak yang tidak pernah dikenai konfigurasi batas milik Release. Hubungan yang sama diperiksa dari sisi Release: entri batas yang menyebut komponen yang tidak dimuat topologi tidak mengonfigurasi apa pun, sehingga entri itu juga menghentikan build dan diagnostiknya melaporkan id yang dituju entri tersebut. aggrega pull berbagi bentuk dengan Release sebagai input; aggrega inspect menerima entitas apa pun — nama katalog, berkas entitas, referensi registry, atau Release; aggrega push menerima entitas katalog; aggrega validate dan aggrega lint menerima entitas katalog, Release (melalui --release), atau seluruh katalog; aggrega serve berjalan sebagai proses berumur panjang. Halaman flag global mendokumentasikan flag yang berlaku di semua subperintah.

Apa yang boleh diubah sebuah rilis pada perintah, flag, dan alat asisten — serta apa yang tidak pernah diubah oleh rilis patch — dinyatakan di Kompatibilitas.

Referensi per perintah

  • aggrega build — perintah kompilasi utama. Membaca penunjuk Release, meresolusikan Aggregate dan Manifest yang direferensikannya, dan menghasilkan artefak hasil kompilasi per batas.
  • aggrega inspect — tampilan yang mudah dibaca untuk entitas apa pun: entitas katalog berdasarkan nama, berkas entitas berdasarkan path, entitas yang dipublikasikan yang dibaca langsung dari registry-nya, atau Release yang telah diresolusi sepenuhnya, yang IR Graph-nya ditulis --ir-graph sebagai JSON dan yang closure dependensinya dilaporkan --closure.
  • aggrega pull — meresolusikan dependensi Release dan menulis lockfile per Release yang menyematkan setiap dependensi; menyimpan entitas katalog dan artefak sumber ke cache.
  • aggrega push — memublikasikan entitas katalog ke registry OCI, secara opsional menandatanganinya pada saat push.
  • aggrega sign — menandatangani satu atau beberapa artefak yang sudah dipublikasikan dan melampirkan setiap tanda tangan sebagai referrer OCI.
  • aggrega auth token — memperoleh token identitas OIDC secara interaktif dan mencetaknya ke stdout, untuk satu kali autentikasi bagi sekumpulan penandatanganan keyless.
  • aggrega registry — mengelola registry yang dikenal workspace dan kebijakan kepercayaan tanda tangannya: menambahkan, mencantumkan, dan menghapus entri, serta membangun indeks lokal yang dapat dicari dari metadata katalog yang dipublikasikan dengan registry update.
  • aggrega search — mencari entitas katalog yang dipublikasikan dan plugin CLI yang dapat diinstal di indeks lokal registry yang dikonfigurasi, dengan mencocokkan kueri teks bebas dan filter faset opsional.
  • aggrega validate — memeriksa kebenaran (skema, pilar, resolusi referensi, extends, kapabilitas jenis input, render terisolasi) di seluruh katalog, closure dependensi Release (--release), atau satu entitas.
  • aggrega lint — memeriksa konvensi publikasi di seluruh katalog, closure dependensi Release (--release), atau satu entitas; --pre-publish menambahkan gerbang kenaikan versi yang memperhitungkan registry.
  • aggrega serve — daemon compiler-sebagai-layanan yang berjalan lama (JSON-RPC melalui stdin/stdout) untuk integrasi IDE.
  • aggrega version — mencetak versi CLI; -o json menghasilkan objek yang dapat dibaca mesin.
  • aggrega get-schema — mencetak JSON Schema kanonis untuk jenis entitas atau kontrak; --list menyebut setiap jenis. Bentuk otoritatif yang menjadi acuan saat menulis file.
  • aggrega scaffold — mencetak dokumen awal untuk jenis entitas, yang diturunkan dari skema jenis tersebut: field wajib, dengan field tetap sudah terisi dan placeholder di setiap tempat yang memerlukan nilai. Penyusunan draf tidak menulis file; arahkan output-nya ke tempat yang Anda inginkan. Dengan --example, perintah ini justru menulis salah satu contoh yang dapat dijalankan dari dokumentasi ke direktori baru, dan --example --list menyebutkan contoh-contoh tersebut.
  • aggrega mcp — menjalankan server Model Context Protocol, melalui input dan output standar atau melalui HTTP, sehingga klien yang mendukung MCP menjadi asisten penulisan yang memahami Aggrega. Lihat Menulis file Aggrega.
  • aggrega skills — memasang skill yang mengajari asisten AI cara memasang dan menggunakan Aggrega ke folder skill asisten tersebut, untuk satu proyek atau, dengan --global, untuk setiap proyek Anda.
  • aggrega cache — memeriksa dan memelihara cache di disk: mencantumkan isinya, mengambil kembali entri cache artefak yang tidak dirujuk lockfile mana pun, memangkas cache modul terkompilasi hingga batas ukuran, atau menghapus setiap cache.
  • aggrega config — memeriksa dan mengelola konfigurasi yang dibaca Aggrega: menampilkan apa yang berlaku dan lapisan mana yang menentukan setiap pengaturan, menyiapkan konfigurasi yang berfungsi, dan membekukan pengaturan yang penting bagi build ke dalam workspace.
  • aggrega deprecate — melampirkan penanda deprecation yang ditandatangani ke artefak yang sudah dipublikasikan.
  • aggrega edit-document — menerapkan satu suntingan terstruktur yang terbatas ke sebuah dokumen, dengan mempertahankan setiap byte yang tidak disentuhnya.
  • aggrega explain — menjelaskan kondisi penghentian yang dinamai oleh sebuah kode.
  • aggrega import — mengubah deskripsi sumber asing menjadi draf berkas authoring Aggrega.
  • aggrega login — mengautentikasi ke registry OCI dan menyimpan kredensial yang disajikan oleh push, pull, dan lint --pre-publish.
  • aggrega logout — menghapus kredensial registry yang tersimpan.
  • aggrega pin — mencatat pin konten untuk input eksternal sebuah entitas di entity.lock di sampingnya.
  • aggrega plugin — mencantumkan plugin Wasm yang dapat diresolusi CLI, menambahkan atau menghapus binding workspace, dan memeriksa guest sebelum Anda memublikasikannya.
  • aggrega push-artifact — memublikasikan artefak data mandiri, seperti bundel dokumentasi, ke registry OCI di bawah namespace docs/-nya.
  • Konfigurasi — di file mana sebuah pengaturan diletakkan, dan bagaimana lapisan-lapisannya digabungkan. Mulailah dari sini: halaman ini dibuka dengan dua file yang dibutuhkan sebagian besar proyek dan menempatkan mekanisme yang diperlukan proyek yang lebih besar di bagian belakang.
  • Flag global — flag yang digunakan bersama di seluruh subperintah (root workspace, berkas konfigurasi global, output berwarna dan output polos yang aksesibel, dan mode offline). Mode offline juga dapat diaktifkan sebagai pengaturan konfigurasi dan variabel lingkungan — lihat Konfigurasi, skema konfigurasi, dan variabel lingkungan.
  • Batas workspace — apa yang berada di dalam workspace, apa akibat tautan simbolik yang mengarah ke luar workspace terhadap setiap jenis jalur, jalur yang sengaja menjangkau ke luar, dan apa yang harus dilakukan ketika salah satunya ditolak.
PerintahDeskripsi
aggrega authMengelola identitas penandatanganan
aggrega buildMengompilasi Aggregate dan Release menjadi artefak asli provider di bawah dist/ pada akar workspace
aggrega cacheMemeriksa dan memelihara cache di disk
aggrega configMemeriksa dan mengelola konfigurasi workspace
aggrega deprecateMelampirkan penanda deprekasi bertanda tangan ke artefak yang sudah dipublikasikan
aggrega edit-documentMenerapkan satu suntingan terstruktur yang terbatas pada dokumen, dengan mempertahankan setiap byte yang tidak disentuhnya
aggrega explainMenjelaskan kondisi penghentian yang dinamai oleh sebuah kode
aggrega get-schemaMencetak JSON Schema untuk jenis entitas atau kontrak
aggrega importMengubah deskripsi sumber asing menjadi draf file penulisan Aggrega
aggrega inspectMemeriksa entitas katalog berdasarkan nama, file entitas berdasarkan jalur, atau entitas yang dipublikasikan berdasarkan referensi registry-nya
aggrega lintMemeriksa konvensi publikasi katalog di seluruh katalog, sebuah Release, atau satu entitas
aggrega loginMengautentikasi ke registry OCI dan menyimpan kredensialnya
aggrega logoutMenghapus kredensial registry yang tersimpan
aggrega mcpMenjalankan server Model Context Protocol melalui input dan output standar, atau melalui HTTP, untuk integrasi asisten AI
aggrega pinMencatat pin konten untuk input eksternal sebuah entitas di entity.lock yang berada di sampingnya
aggrega pluginMemeriksa plugin Wasm yang dapat diresolusikan CLI
aggrega pullMeresolusikan dependensi katalog dan sumber ke dalam cache dan menulis lockfile per Release
aggrega pushMembundel dan memublikasikan entitas katalog ke registry OCI
aggrega push-artifactMemublikasikan artefak data mandiri (seperti bundel dokumentasi) ke registry OCI
aggrega registryMengelola registry dan kebijakan kepercayaan tanda tangannya
aggrega scaffoldMenyusun draf dokumen awal untuk jenis entitas, atau menulis contoh yang dapat dijalankan ke direktori baru
aggrega searchMencari di indeks lokal registry yang dikonfigurasi
aggrega serveBerjalan sebagai compiler-sebagai-layanan berumur panjang melalui JSON-RPC 2.0 pada stdin/stdout
aggrega signMenandatangani satu atau beberapa artefak yang sudah dipublikasikan dan melampirkan tanda tangannya
aggrega skillsMemasang skill Aggrega ke asisten AI
aggrega validateMemeriksa kebenaran di seluruh katalog, sebuah Release, atau satu entitas
aggrega versionMencetak versi CLI aggrega

Argumen posisional dan status keluar

Setiap perintah menolak argumen posisional yang tidak digunakannya, dan melaporkan penolakan itu melalui status keluar bukan nol alih-alih selesai seolah-olah pemanggilan tersebut valid. Aturan ini mencakup perintah yang hanya ada untuk mengelompokkan subperintah, tempat nama subperintah yang salah ketik tiba sebagai argumen posisional yang tidak dikenali: bantuan perintah dicetak dan status keluarnya bukan nol, sehingga salah ketik dalam skrip gagal secara jelas alih-alih terbaca sebagai eksekusi yang berhasil. aggrega yang dipanggil dengan perintah yang tidak dikenali berperilaku sama dan juga menyebutkan perintah yang paling mirip, jika ada yang cukup mirip.

Perintah yang tidak dikenali juga memberi tahu cara menemukan plugin CLI dengan nama tersebut. Jawabannya berasal dari indeks lokal registri default yang dibangun oleh aggrega registry update dan dibaca oleh aggrega search, sehingga jawabannya langsung kembali dan kata yang salah ketik tidak pernah dikirim ke registri, baik daring maupun luring. Jika indeks memuat plugin CLI dengan nama tersebut, pesan menyebutkan perintah aggrega plugin add cli <name> yang memasangnya. Jika indeks tidak memuatnya, pesan menyebutkan pencarian untuk menemukannya, aggrega search <name> --kind plugin --plugin-type cli. Jika belum ada indeks yang dibangun, pesan menyebutkan aggrega plugin add cli <name>, yang mencari plugin dengan nama tersebut di registri dan menolak jika tidak ada yang dipublikasikan. Kedua perintah tersebut memuat nama yang dikutip untuk shell bila perlu.

Di tempat argumen posisional bermakna, halaman referensi setiap perintah mendokumentasikan apa yang diterimanya. Plugin CLI yang terpasang adalah pengecualian yang disengaja: perintahnya menangani sendiri penguraian argumen, sehingga seluruh vektor argumen diteruskan ke plugin, yang menjadi satu-satunya pengurai argumennya sendiri — dan status keluar plugin itu sendiri adalah yang dikembalikan oleh pemanggilan.

Kemajuan, dan berapa lama perintah menunggu registri

Perintah yang menunggu menyatakan apa yang ditunggunya. Di mana pun sebuah perintah menunggu registri, unduhan, atau kompilasi pertama sebuah plugin, perintah itu menampilkan langkah tersebut di standard error, seperti aggrega build dan aggrega pull menampilkan langkah-langkahnya: di terminal, sebuah baris yang menyebutkan langkah tersebut dengan indikator berputar dan waktu yang telah dihabiskan sejauh ini, dicentang setelah langkah selesai dan dibiarkan tanpa centang jika langkah gagal; di terminal yang tidak dapat menggambar ulang di tempat, atau dengan --plain, satu baris per langkah saat langkah itu berakhir, beserta waktunya. Jika standard error bukan terminal, tidak ada yang ditampilkan, dan apa pun yang dicetak perintah ke standard output tidak berubah dalam kedua kasus. Sebuah langkah hanya ditampilkan selama perintah benar-benar menunggunya, sehingga eksekusi yang dilayani dari cache tidak menampilkan apa pun, dan kompilasi plugin hanya ditampilkan jika memakan waktu cukup lama untuk menjadi kompilasi sungguhan, bukan kompilasi dari cache.

Perintah yang menampilkan langkah-langkahnya dengan cara ini, selain perintah setiap plugin CLI yang terpasang:

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

Tidak ada permintaan yang menunggu server tanpa batas. Sebuah permintaan menunggu paling lama 30 detik agar server mulai menjawab setelah permintaan terkirim sepenuhnya, dan paling lama 30 detik untuk bagian berikutnya dari jawaban yang sudah mulai tiba. Server yang membuat permintaan menunggu lebih lama ditolak dengan E0376, yang menyebutkan server dan waktu tunggunya. Hanya penantian yang dibatasi: unduhan atau unggahan yang terus berjalan memakan waktu selama yang dibutuhkan. Chart Helm yang diambil source: sebuah Recipe melalui HTTPS hanya tunduk pada penantian pertama dari keduanya, dan kedaluwarsanya dilaporkan dengan kata-kata pustaka jaringan itu sendiri, bukan dengan E0376. Permintaan yang memang sudah diulang oleh sebuah perintah saat waktunya habis — pembacaan selama aggrega registry update, penulisan selama publikasi — diulang sebelum penolakan dilaporkan.

Penelusuran seluruh daftar repositori sebuah registri berakhir dalam lima menit. Beberapa registri mengumpulkan semua repositori yang dimilikinya sebelum menjawab permintaan daftar sama sekali, sehingga setiap halaman daftar ditunggu selama penelusuran dapat berjalan, bukan selama 30 detik; daftar yang belum berakhir setelah lima menit dihentikan dan ditolak dengan E0377. aggrega plugin add menelusuri daftar hanya jika tidak ada plugin yang memiliki nama persis seperti yang diberikan kepadanya, untuk menemukan plugin yang namanya mengandung nama tersebut, sehingga menyebutkan nama plugin secara persis tidak pernah menunggu penelusuran.

Registry yang meminta untuk memperlambat akan ditunggu, sampai registry itu memintanya selama lima menit tanpa jeda. Sebuah perintah menunggu selama yang diminta registry semacam itu, mengirim lebih sedikit permintaan sekaligus kepadanya, dan menampilkan penantian itu bersama progres lainnya; registry yang selama lima menit tidak menjawab apa pun selain “perlambat” ditolak dengan E0378. Registry yang meminta untuk memperlambat menjelaskan caranya.

Ketiga batas tersebut tetap; tidak ada pengaturan yang mengubahnya.

Path yang Anda ketik, dan batas workspace

Path yang Anda ketik di baris perintah — sebuah --release, sebuah --catalog, sebuah --output-dir, berkas yang akan divalidasi, di-lint, disematkan, atau dipublikasikan, sebuah --workspace-root — digunakan di tempat yang ditujunya, di dalam atau di luar workspace, melalui tautan apa pun di sepanjang jalan. Apa yang kemudian dibaca dan ditulis perintah atas namanya sendiri tetap terikat pada workspace, siapa pun yang menjalankannya: perintah tidak membaca berkas konfigurasi workspace, dokumen katalog, dokumen di samping sebuah Release, atau lockfile sebuah Release melalui tautan yang mengarah keluar dari workspace, tidak mengikuti path yang ditulis sebuah Release atau Manifest ke luar workspace, dan tidak menulis output, lockfile, atau cache-nya melalui tautan semacam itu. Direktori yang Anda sebutkan di luar workspace diperlakukan sama untuk apa yang ada di bawahnya, dan sebuah Release yang Anda sebutkan di luar workspace hanya menjangkau berkas di direktorinya sendiri. aggrega edit-document adalah satu-satunya perintah yang path ketikannya juga terikat: perintah ini hanya mengedit dokumen yang dimuat workspace. Batas workspace menyatakan aturannya, path yang sengaja menjangkau ke luar, dan solusi untuk setiap penolakan.

Mencari di indeks katalog

aggrega search [query] mencari entitas yang dipublikasikan di seluruh registry yang dikenal workspace. [query] yang opsional adalah substring yang tidak peka huruf besar-kecil dan dicocokkan dengan nama dan deskripsi setiap entitas. Filter faset mempersempit kumpulan hasil:

  • --kind membatasi ke satu atau beberapa jenis entitas (component, feature, recipe, featurerecipe, workload, plugin); flag ini dapat diulang dan tidak peka huruf besar-kecil, dan jenis-jenisnya digabungkan sebagai OR.
  • -l/--selector memfilter berdasarkan label katalog entitas. Kategori adalah label, bukan flag khusus: -l component.aggrega.ai/category=datastore.
  • --capability dan --plugin-type memfilter plugin berdasarkan kapabilitas yang dideklarasikan atau tipe socket; --capability dapat diulang dan digabungkan sebagai OR.
  • --registry membatasi pencarian ke satu registry berdasarkan host atau alias; secara default, setiap registry yang dikonfigurasi akan dicari.
  • --limit membatasi jumlah hasil.
  • -o/--output memilih format output: table (default, mudah dibaca manusia), json (array yang dapat dibaca mesin), atau names (pengenal saja, satu per baris).

Pencarian selalu membaca indeks lokal — snapshot offline yang dibangun dan diperbarui oleh aggrega registry update. Pencarian tidak menghubungi jaringan apa pun dan tidak mengambil apa pun sesuai permintaan. Jika indeks tidak ada, perintah gagal dan meminta Anda menjalankan aggrega registry update terlebih dahulu. Setiap eksekusi mencetak baris kesegaran “last updated” per registry ke standard error, sehingga output json dan names di standard out tetap bersih untuk skrip.

Pelengkapan shell

aggrega completion <shell> mencetak skrip pelengkapan ke stdout untuk bash, zsh, fish, atau powershell. Skrip dihasilkan dari pohon perintah CLI yang aktif pada saat Anda menjalankannya, sehingga selalu mencerminkan perintah dan flag dari biner yang menghasilkannya — tidak ada berkas statis yang perlu dibuat ulang seiring berkembangnya CLI.

Untuk mencoba pelengkapan di sesi Anda saat ini tanpa memasang apa pun, muat skrip secara langsung dengan source:

Terminal window
source <(aggrega completion bash)

Untuk memasang pelengkapan secara permanen, tulis skrip ke lokasi yang dibaca shell Anda saat dimulai.

bash

Pelengkapan Bash bergantung pada paket bash-completion; pasang paket tersebut melalui pengelola paket sistem operasi Anda jika belum tersedia.

Terminal window
# Linux
aggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)
aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggrega

zsh

Jika pelengkapan belum diaktifkan di shell Anda, aktifkan sekali:

Terminal window
echo "autoload -U compinit; compinit" >> ~/.zshrc

Lalu tulis skrip pelengkapan ke sebuah direktori di fpath Anda:

Terminal window
# Linux
aggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)
aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggrega

fish

Terminal window
aggrega completion fish > ~/.config/fish/completions/aggrega.fish

powershell

Tambahkan skrip yang dihasilkan ke profil PowerShell Anda agar dimuat di setiap sesi:

Terminal window
aggrega completion powershell >> $PROFILE

Mulai shell baru agar pelengkapan yang dipasang berlaku.