Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Panoramica della CLI

La CLI aggrega è il punto di ingresso del compilatore. Ogni interazione con Aggrega — compilare un Aggregate in artefatti distribuibili, ispezionare il catalogo o l’IR, risolvere e bloccare le dipendenze, pubblicare entità di catalogo, verificare la correttezza con validate, verificare le convenzioni di pubblicazione con lint e servire un IDE — passa per un sottocomando di aggrega. Questo insieme di capitoli tratta i flag, gli input e gli output di ciascun sottocomando.

aggrega validate e aggrega lint sono controlli complementari, ciascuno dei quali rispecchia i tre ambiti dell’altro: l’intero catalogo, la chiusura delle dipendenze di una Release o una singola entità. aggrega validate verifica la correttezza (schema, pilastri, risoluzione dei riferimenti, extends, capability di tipo di input del provider e — per un’entità di rendering — un rendering isolato); aggrega lint verifica le convenzioni di pubblicazione (denominazione, allineamento alla directory di categoria, prefissi delle annotazioni ed entità dell’incremento di versione). Nessuno dei due emette artefatti; usa validate per rispondere a «è corretto?» e lint per rispondere a «segue la disciplina di pubblicazione del catalogo?».

aggrega build segue il principio del punto di ingresso unico: la Release è l’unico input di compilazione. aggrega build --release release.yaml legge i puntatori aggregate: e manifest: della Release per individuare il resto della topologia, e produce output per confine sotto dist/: un confine con nome viene prodotto sotto la directory: dichiarata, oppure sotto dist/boundaries/<boundary-name>/ quando non ne dichiara alcuna; una Release che dichiara components: di primo livello invece di confini con nome viene prodotta in modo piatto sotto dist/. Ogni componente contenuto nella topologia deve appartenere a uno di quei confini, e un componente che nessuno di essi contiene arresta la build: un componente raggiunge un confine o perché è nominato sotto i components: di quel confine, con l’id che porta una volta appiattiti i sotto-Aggregates, o perché si trova all’interno di un sotto-Aggregate che il confine instrada sotto aggregates:. Un componente che non raggiunge né l’uno né l’altro verrebbe prodotto fuori da ogni confine dichiarato dalla Release, senza alcuna fonte per la propria posizione di output, la sync wave, le annotazioni e l’infra: per componente, quindi la build si ferma e nomina il componente anziché emettere artefatti a cui la configurazione dei confini della Release non è mai stata applicata. La stessa relazione viene verificata dal lato della Release: una voce di confine che nomina un componente non contenuto nella topologia non configura nulla, quindi arresta anch’essa la build e la diagnostica riporta l’id a cui la voce si rivolgeva. aggrega pull condivide la forma con la Release come input; aggrega inspect accetta qualsiasi entità — un nome di catalogo, un file di entità, un riferimento di registry o una Release; aggrega push prende un’entità di catalogo; aggrega validate e aggrega lint accettano un’entità di catalogo, una Release (tramite --release) o l’intero catalogo; aggrega serve viene eseguito come processo di lunga durata. La pagina dei flag globali documenta i flag che si applicano a tutti i sottocomandi.

Che cosa una release può cambiare nei comandi, nei flag e negli strumenti dell’assistente — e che cosa una release di patch non cambia mai — è indicato in Compatibilità.

Riferimento per comando

  • aggrega build — il comando di compilazione principale. Legge un puntatore a una Release, risolve l’Aggregate e il Manifest a cui fa riferimento ed emette artefatti compilati per confine.
  • aggrega inspect — una vista leggibile di qualsiasi entità: un’entità di catalogo per nome, un file di entità per percorso, un’entità pubblicata letta direttamente dal suo registry, o una Release completamente risolta, il cui IR Graph viene scritto come JSON da --ir-graph e la cui chiusura delle dipendenze viene riportata da --closure.
  • aggrega pull — risolve le dipendenze di una Release e scrive un lockfile per Release che blocca ogni dipendenza; mette in cache le entità di catalogo e gli artefatti sorgente.
  • aggrega push — pubblica un’entità di catalogo in un registry OCI, firmandola facoltativamente al momento del push.
  • aggrega sign — firma uno o più artefatti già pubblicati e collega ogni firma come referrer OCI.
  • aggrega auth token — ottiene in modo interattivo un token di identità OIDC e lo stampa su stdout, per un’unica autenticazione valida per un lotto di firme keyless.
  • aggrega registry — gestisce i registry noti al workspace e la loro policy di fiducia delle firme: aggiunge, elenca e rimuove voci, e costruisce con registry update un indice locale ricercabile dei metadati di catalogo pubblicati.
  • aggrega search — cerca nell’indice locale dei registry configurati le entità di catalogo pubblicate e i plugin CLI installabili, in base a una query a testo libero e a filtri di facet facoltativi.
  • aggrega validate — verifica la correttezza (schema, pilastri, risoluzione dei riferimenti, extends, capability di tipo di input, rendering isolato) sull’intero catalogo, sulla chiusura delle dipendenze di una Release (--release) o su una singola entità.
  • aggrega lint — verifica le convenzioni di pubblicazione sull’intero catalogo, sulla chiusura delle dipendenze di una Release (--release) o su una singola entità; --pre-publish aggiunge il controllo dell’incremento di versione basato sul registry.
  • aggrega serve — un daemon di lunga durata che espone il compilatore come servizio (JSON-RPC su stdin/stdout) per l’integrazione con gli IDE.
  • aggrega version — stampa la versione della CLI; -o json emette un oggetto leggibile da macchina.
  • aggrega get-schema — stampa lo JSON Schema canonico di un tipo di entità o di contratto; --list nomina ogni tipo. La forma autorevole rispetto a cui scrivere un file.
  • aggrega scaffold — stampa un documento iniziale per un tipo di entità, ricavato dallo schema di quel tipo: i campi obbligatori, con quelli fissi già compilati e un segnaposto ovunque serva un valore. La bozza non scrive alcun file; reindirizzane l’output dove vuoi. Con --example scrive invece uno degli esempi eseguibili della documentazione in una nuova directory, e --example --list li elenca.
  • aggrega mcp — esegue un server Model Context Protocol, su standard input e output o su HTTP, così che un client compatibile con MCP diventi un assistente di authoring che conosce Aggrega. Vedi Scrivere i file Aggrega.
  • aggrega skills — installa la skill che insegna a un assistente AI a installare e usare Aggrega nella cartella delle skill di quell’assistente, per un progetto o, con --global, per ogni tuo progetto.
  • aggrega cache — ispeziona e mantiene le cache su disco: elenca ciò che contengono, recupera le voci della cache degli artifact a cui nessun lockfile fa riferimento, riduce la cache dei moduli compilati entro un limite di dimensione o svuota ogni cache.
  • aggrega config — ispeziona e gestisce la configurazione che Aggrega legge: mostra ciò che si applica e quale livello ha deciso ciascuna impostazione, crea una configurazione funzionante e congela nel workspace le impostazioni critiche per la build.
  • aggrega deprecate — allega un marcatore di deprecazione firmato a un artifact già pubblicato.
  • aggrega edit-document — applica a un documento una singola modifica strutturata e delimitata, preservando ogni byte che non tocca.
  • aggrega explain — spiega la condizione di arresto che un codice nomina.
  • aggrega import — trasforma la descrizione di una sorgente esterna in bozze di file di authoring Aggrega.
  • aggrega login — si autentica presso un registry OCI e memorizza la credenziale che presentano push, pull e lint --pre-publish.
  • aggrega logout — rimuove una credenziale di registry memorizzata.
  • aggrega pin — registra i pin di contenuto per gli input esterni di un’entità nell’entity.lock accanto a essa.
  • aggrega plugin — elenca i plugin Wasm che la CLI può risolvere, aggiunge o rimuove un binding del workspace e verifica un guest prima che tu lo pubblichi.
  • aggrega push-artifact — pubblica un artifact di dati autonomo, come un bundle di documentazione, su un registry OCI sotto il suo namespace docs/.
  • Configurazione — in quale file va un’impostazione, e come si combinano i livelli. Inizia da qui: si apre con i due file di cui la maggior parte dei progetti ha bisogno e lascia dietro di essi i meccanismi a cui ricorre un progetto più grande.
  • Flag globali — flag condivisi tra i sottocomandi (la radice del workspace, il file di configurazione globale, l’output a colori e quello semplice accessibile, e la modalità offline). La modalità offline è disponibile anche come impostazione di configurazione e come variabile d’ambiente: vedi Configurazione, lo schema di configurazione e le variabili d’ambiente.
  • Il confine del workspace — che cosa si trova all’interno di un workspace, che effetto ha su ciascun tipo di percorso un link simbolico che ne esce, i percorsi che escono di proposito e che cosa fare quando uno viene rifiutato.
ComandoDescrizione
aggrega authGestisce l’identità di firma
aggrega buildCompila un Aggregate e una Release in artefatti nativi del provider sotto dist/ alla radice del workspace
aggrega cacheIspeziona e mantiene le cache su disco
aggrega configIspeziona e gestisce la configurazione del workspace
aggrega deprecateCollega un marcatore di deprecazione firmato a un artefatto già pubblicato
aggrega edit-documentApplica a un documento una modifica strutturata e circoscritta, preservando ogni byte che non tocca
aggrega explainSpiega la condizione di arresto nominata da un codice
aggrega get-schemaStampa lo JSON Schema di un tipo di entità o di contratto
aggrega importTrasforma la descrizione di un sorgente esterno in bozze di file di authoring Aggrega
aggrega inspectIspeziona un’entità di catalogo per nome, un file di entità per percorso o un’entità pubblicata per riferimento di registry
aggrega lintVerifica le convenzioni di pubblicazione del catalogo sul catalogo, su una Release o su una singola entità
aggrega loginSi autentica a un registry OCI e memorizza la credenziale
aggrega logoutRimuove una credenziale di registry memorizzata
aggrega mcpEsegue un server Model Context Protocol su standard input e output, o su HTTP, per l’integrazione con assistenti IA
aggrega pinRegistra i pin di contenuto per gli input esterni di un’entità nell’entity.lock accanto a essa
aggrega pluginIspeziona i plugin Wasm che la CLI può risolvere
aggrega pullRisolve le dipendenze di catalogo e di sorgente nella cache e scrive il lockfile per Release
aggrega pushImpacchetta e pubblica un’entità di catalogo in un registry OCI
aggrega push-artifactPubblica un artefatto di dati autonomo (come un bundle di documentazione) in un registry OCI
aggrega registryGestisce i registry e la loro policy di fiducia delle firme
aggrega scaffoldPrepara un documento iniziale per un tipo di entità, o scrive un esempio eseguibile in una nuova directory
aggrega searchCerca nell’indice locale dei registry configurati
aggrega serveViene eseguito come compilatore-come-servizio di lunga durata su JSON-RPC 2.0 su stdin/stdout
aggrega signFirma uno o più artefatti già pubblicati e ne collega le firme
aggrega skillsInstalla la skill di Aggrega in un assistente AI
aggrega validateVerifica la correttezza sul catalogo, su una Release o su una singola entità
aggrega versionStampa la versione della CLI aggrega

Argomenti posizionali e stato di uscita

Ogni comando rifiuta un argomento posizionale di cui non ha bisogno e segnala il rifiuto con uno stato di uscita diverso da zero, invece di completare come se l’invocazione fosse valida. La regola copre i comandi che esistono solo per raggruppare sottocomandi, dove un nome di sottocomando digitato male arriva come argomento posizionale non riconosciuto: viene stampato l’help del comando e lo stato di uscita è diverso da zero, così un errore di battitura in uno script fallisce in modo evidente invece di sembrare un’esecuzione riuscita. aggrega invocato con un comando non riconosciuto si comporta allo stesso modo e indica inoltre il comando più simile, se ce n’è uno abbastanza vicino.

Un comando non riconosciuto indica anche come trovare un plugin della CLI con quel nome. La risposta viene dall’indice locale del registry predefinito che aggrega registry update costruisce e aggrega search legge, quindi arriva subito e la parola digitata male non viene mai inviata a un registry, né online né offline. Se l’indice contiene un plugin della CLI con quel nome, il messaggio indica il comando aggrega plugin add cli <name> che lo installa. Se l’indice non ne contiene alcuno, indica la ricerca che ne cerca uno, aggrega search <name> --kind plugin --plugin-type cli. Se non è ancora stato costruito alcun indice, indica aggrega plugin add cli <name>, che cerca il plugin con quel nome nel registry e rifiuta se non ne è pubblicato alcuno. Ciascuno dei due comandi riporta il nome racchiuso tra virgolette per la shell dove serve.

Dove gli argomenti posizionali hanno un significato, la pagina di riferimento di ciascun comando documenta cosa accetta. Un plugin della CLI installato è l’eccezione voluta: il suo comando gestisce da sé il parsing degli argomenti, quindi l’intero vettore di argomenti viene inoltrato al plugin, che è l’unico parser dei propri argomenti — e lo stato di uscita del plugin stesso è quello che l’invocazione restituisce.

Avanzamento, e quanto a lungo un comando attende un registry

Un comando che attende dice che cosa sta attendendo. Ovunque un comando attenda un registry, un download o la prima compilazione di un plugin, mostra quel passaggio sullo standard error, come aggrega build e aggrega pull mostrano i loro: su un terminale, una riga che nomina il passaggio con un indicatore rotante e il tempo impiegato finora, spuntata una volta completato il passaggio e lasciata senza spunta se il passaggio non è riuscito; su un terminale che non può ridisegnare sul posto, o con --plain, una riga per passaggio quando termina, con il suo tempo. Se lo standard error non è un terminale, non viene mostrato nulla, e in nessuno dei due casi cambia nulla di ciò che un comando stampa sullo standard output. Un passaggio viene mostrato solo mentre il comando lo attende davvero, quindi un’esecuzione servita dalla cache non mostra nulla, e la compilazione di un plugin viene mostrata solo quando dura abbastanza da essere una vera compilazione anziché una presa dalla cache.

I comandi che mostrano i loro passaggi in questo modo, oltre al comando di ogni plugin della CLI installato:

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

Nessuna richiesta attende un server all’infinito. Una richiesta attende al massimo 30 secondi che il server inizi la sua risposta una volta che la richiesta è stata inviata per intero, e al massimo 30 secondi la parte successiva di una risposta che sta già arrivando. Un server che fa attendere una richiesta più a lungo viene rifiutato con E0376, che nomina il server e l’attesa. Solo l’attesa è limitata: un download o un upload che continua ad avanzare dura quanto serve. Un chart Helm che il source: di una Recipe scarica via HTTPS è soggetto solo alla prima delle due attese, e la sua scadenza viene riportata con le parole della libreria di rete anziché con E0376. Una richiesta che un comando già ripete quando va in timeout — una lettura durante aggrega registry update, una scrittura durante una pubblicazione — viene ripetuta prima che il rifiuto sia riportato.

La visita dell’intero elenco dei repository di un registry termina entro cinque minuti. Alcuni registry raccolgono tutti i repository che contengono prima ancora di rispondere a una richiesta di elenco, quindi ogni pagina dell’elenco viene attesa per tutto il tempo che la visita può durare anziché per 30 secondi; un elenco che non è terminato dopo cinque minuti viene interrotto e rifiutato con E0377. aggrega plugin add visita l’elenco solo quando nessun plugin porta esattamente il nome ricevuto, per trovarne uno il cui nome lo contenga, quindi indicare il plugin con il suo nome esatto non attende mai la visita.

Si aspetta un registry che chiede di rallentare, finché non lo ha chiesto per cinque minuti senza interruzioni. Un comando attende quanto chiede un tale registry, gli invia meno richieste contemporaneamente e mostra l’attesa insieme al resto del suo avanzamento; un registry che per cinque minuti non risponde altro che «rallenta» viene rifiutato con E0378. Un registry che chiede di rallentare descrive come.

I tre limiti sono fissi; non esiste alcuna impostazione che li modifichi.

I percorsi che digiti e il confine del workspace

Un percorso che digiti sulla riga di comando — un --release, un --catalog, un --output-dir, un file da validare, sottoporre a lint, fissare o pubblicare, un --workspace-root — viene usato dove porta, dentro o fuori dal workspace, attraverso qualsiasi link lungo il tragitto. Ciò che il comando poi legge e scrive per conto proprio resta vincolato al workspace, chiunque lo esegua: non legge i file di configurazione del workspace, un documento del catalogo, un documento accanto a una Release o il lockfile di una Release attraverso un link che porta fuori dal workspace, non segue un percorso che una Release o un Manifest scrive fuori da esso e non scrive il proprio output, il proprio lockfile o la propria cache attraverso un link simile. Una directory che indichi fuori dal workspace è vincolata allo stesso modo per ciò che contiene, e una Release che indichi fuori dal workspace raggiunge solo i file nella propria directory. aggrega edit-document è l’unico comando il cui percorso digitato è anch’esso vincolato: modifica solo un documento contenuto nel workspace. Il confine del workspace enuncia la regola, i percorsi che escono di proposito e il rimedio per ciascun rifiuto.

Ricerca nell’indice del catalogo

aggrega search [query] cerca le entità pubblicate nei registry noti al workspace. Il facoltativo [query] è una sottostringa, senza distinzione tra maiuscole e minuscole, confrontata con il nome e la descrizione di ciascuna entità. I filtri per facet restringono l’insieme dei risultati:

  • --kind limita i risultati a uno o più tipi di entità (component, feature, recipe, featurerecipe, workload, plugin); è ripetibile e non distingue tra maiuscole e minuscole, e i tipi si combinano in OR.
  • -l/--selector filtra in base alle label di catalogo dell’entità. La categoria è una label, non un flag dedicato: -l component.aggrega.ai/category=datastore.
  • --capability e --plugin-type filtrano i plugin per una capability dichiarata o per tipo di socket; --capability è ripetibile e si combina in OR.
  • --registry limita la ricerca a un singolo registry, indicato per host o per alias descrittivo; per impostazione predefinita la ricerca avviene in tutti i registry configurati.
  • --limit fissa il numero massimo di risultati.
  • -o/--output seleziona il formato di output: table (il predefinito, leggibile da una persona), json (un array leggibile da una macchina) o names (identificatori semplici, uno per riga).

La ricerca legge sempre l’indice locale — lo snapshot offline che aggrega registry update costruisce e aggiorna. Non contatta la rete e non scarica nulla su richiesta. Quando l’indice è assente, il comando fallisce e ti dice di eseguire prima aggrega registry update. Ogni esecuzione stampa sullo standard error, per ciascun registry, una riga di aggiornamento «last updated», così l’output json e names sullo standard output resta pulito per lo scripting.

Completamento della shell

aggrega completion <shell> stampa su stdout uno script di completamento per bash, zsh, fish o powershell. Lo script viene generato dall’albero dei comandi attivo della CLI nel momento in cui lo esegui, quindi riflette sempre i comandi e i flag del binario che lo ha prodotto — non c’è alcun file statico da rigenerare man mano che la CLI cresce.

Per provare il completamento nella sessione corrente senza installare nulla, carica direttamente lo script con source:

Terminal window
source <(aggrega completion bash)

Per installare il completamento in modo permanente, scrivi lo script nella posizione che la tua shell legge all’avvio.

bash

Il completamento di Bash si basa sul pacchetto bash-completion; installalo tramite il gestore di pacchetti del tuo sistema operativo se non è già presente.

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

zsh

Se il completamento non è ancora abilitato nella tua shell, abilitalo una volta:

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

Poi scrivi lo script di completamento in una directory del tuo fpath:

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

Aggiungi lo script generato al tuo profilo PowerShell, così viene caricato in ogni sessione:

Terminal window
aggrega completion powershell >> $PROFILE

Avvia una nuova shell perché il completamento installato abbia effetto.