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

aggrega scaffold

Prepara un documento iniziale per un tipo di entità, o scrive un esempio eseguibile in una nuova directory

Sinossi

aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]

Descrizione

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.

Flag

FlagPredefinitoDescrizione
--examplefalsescrive l’esempio eseguibile nominato dall’argomento in una nuova directory, letto dal bundle firmato della documentazione
--listfalsecon —example, stampa ogni esempio eseguibile pubblicato dalla documentazione e non scrive nulla

Cosa fa

Il comando ha due forme. aggrega scaffold <kind> prepara una bozza di documento iniziale a partire dallo schema di un tipo e la stampa, ed è ciò che descrivono questa sezione e le tre successive. aggrega scaffold --example <name> scrive invece uno degli esempi eseguibili della documentazione in una nuova directory — vedi Partire da un esempio eseguibile.

aggrega scaffold <kind> stampa sullo standard output un documento iniziale per un tipo di entità. Il documento contiene esattamente i campi che lo schema di quel tipo richiede: apiVersion e kind sono compilati, perché lo schema li fissa, e ogni altro valore obbligatorio viene lasciato come segnaposto da sostituire.

Il [name] facoltativo inizializza metadata.name per un tipo il cui schema ne richiede uno:

Terminal window
aggrega scaffold component my-service
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: my-service
version: ""
labels:
component.aggrega.ai/type: ""
spec: {}

Il tipo è il token di schema in minuscolo con trattini — component, aggregate, release, recipe, manifest, feature e così via. aggrega get-schema --list stampa l’insieme completo, e un token a cui non corrisponde alcuno schema viene rifiutato con quell’insieme nel messaggio, così un errore di battitura si corregge senza una seconda ricerca.

Cosa restituisce e cosa no

Il documento deriva dal contratto del tipo stesso e da nient’altro. Non è un esempio svolto. Non ci sono namespace, categorie o valori di etichetta compilati per te, né suggerimenti commentati su ciò che di solito si scrive — perché nessuno di questi è qualcosa che il compilatore richiede. Un catalogo sceglie la propria denominazione, le proprie categorie e la propria struttura di directory; lo schema decide i campi, e lo schema è tutto ciò che questo comando legge. Un documento iniziale che indovinasse il resto ti insegnerebbe una regola che non esiste.

Quando abbozza un documento, non scrive alcun file. Il documento va sullo standard output, quindi è un reindirizzamento a decidere dove finisce, e nulla su disco viene sostituito senza che tu lo chieda:

Terminal window
aggrega scaffold component my-service > my-service.yaml

Non è un’entità finita, ed è questo che significa un segnaposto. Un valore obbligatorio vuoto non è un valore, quindi eseguire aggrega validate sul documento esattamente com’è uscito lo rifiuta e nomina in una volta ogni segnaposto ancora dovuto, ciascuno con ciò che accetta — sopra, la versione e il tipo di componente:

Entity: my-service.yaml
Kind: 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

Ciò che ogni valore accetta viene letto dallo schema del tipo stesso: i valori che accetta dove lo schema li elenca, una versione semantica dove ne richiede una, e altrimenti la descrizione del campo fornita dallo schema stesso. Fornisci quei valori e lo stesso comando accetta il documento. Nulla della sua forma deve cambiare, perché la forma proviene dallo schema.

Un valore è dovuto anche dove lo schema lo accetterebbe vuoto. Una Recipe o FeatureRecipe abbozzata porta capability e implements vuoti. Il loro schema ammette una stringa vuota, ma una stringa vuota non nomina alcun provider né alcun tipo, quindi aggrega validate li indica entrambi come ancora dovuti finché non li compili. Questa lettura riguarda la convalida di un singolo file di entità: un’esecuzione sull’intero catalogo, aggrega validate --release e aggrega build non la applicano. Vedi segnaposto ancora dovuti per ciò che copre. Una Recipe abbozzata, inoltre, non dichiara nessuno dei tipi di input di cui il suo schema chiede almeno uno — source, valuesMapping, workload o artifacts — perché scegliere quale si adatta spetta a te, quindi aggrega validate rifiuta il suo spec finché non ne aggiungi uno.

Lo stesso documento da un assistente o da un editor

Il documento iniziale è composto dagli stessi byte qualunque sia la superficie che lo richiede. Un assistente AI connesso tramite aggrega mcp lo raggiunge come strumento scaffold, che restituisce il documento come testo insieme a un payload leggibile da una macchina. Un editor che pilota aggrega serve lo raggiunge in aggrega/scaffoldEntity. Il documento viene derivato dallo schema una sola volta, quindi quello che abbozzi in un terminale e quello che un assistente abbozza per te sono identici byte per byte.

Scrivere ed elencare gli esempi eseguibili è possibile sulle stesse superfici, con le parole del comando stesso come nomi dei campi. Invia allo strumento scaffold, o a aggrega/scaffoldEntity, example al posto di kind per scriverne uno, dir per nominare la nuova directory relativa alla radice del workspace — lì, una directory con il nome dell’esempio quando non ne invii nessuna — e list: true da solo per ricevere in risposta ogni esempio. L’esempio viene letto dallo stesso bundle, verificato rispetto alla stessa policy e scritto dalla stessa estrazione, quindi i file e i comandi successivi sono gli stessi che al terminale, e così i rifiuti: una directory che contiene qualcosa, una voce che esce dalla directory o che è un link, un bundle che la tua policy non accetta, un workspace offline senza nulla in cache. La risposta è strutturata: per un elenco, examples, ciascuno con il suo name, level e summary; per una scrittura, example, dir, files — i file scritti, relativi a dir — next, i comandi indicati dalla pagina dell’esempio, e version, la versione della documentazione da cui l’esempio è stato letto. La risposta dello strumento scaffold a una scrittura riporta anche output_dir, la posizione della directory — completa su standard input e output, così che un assistente che l’ha nominata in modo relativo a un workspace che non può vedere legga dove è finito l’esempio, e relativa alla radice del workspace su HTTP. Il testo dello strumento scaffold è il resoconto che questo comando stampa, chiuso da una riga che nomina quella posizione quando differisce da dir. Campi di due forme inviati insieme — kind con example, ad esempio — vengono rifiutati con le stesse parole su entrambe le superfici, prima che venga letto qualsiasi cosa. Un editor nomina il workspace nel workspaceRoot della richiesta per la forma con esempio, e dir deve essere un percorso relativo che resta al suo interno e non ne esce tramite un link; su HTTP lo strumento vincola anch’esso dir al workspace che serve, e su standard input e output accetta dir così come è nominato, come accetta ogni percorso. L’indice delle capacità riporta lo strumento scaffold come uno strumento che scrive, a causa di quella forma, e allo stesso modo cli-scaffold, che esegue questo comando in un processo separato.

Partire da un esempio eseguibile

La documentazione contiene esempi eseguibili — ciascuno è una directory che contiene un Aggregate, le sue Releases e tutto ciò da cui viene costruito, con una pagina che spiega come costruirlo. --example ne scrive uno in una nuova directory, così puoi partire da un progetto funzionante invece che da uno vuoto:

Terminal window
aggrega scaffold --example redis-cache
Wrote 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.

Che cosa scrive, e dove. I file dell’esempio, così come la documentazione li contiene, nella directory che indichi come secondo argomento — oppure, se non ne indichi nessuna, in una directory con il nome dell’esempio nella cartella in cui esegui il comando. La directory non deve ancora esistere, oppure deve essere vuota. Qualsiasi altra cosa viene rifiutata e lasciata esattamente com’era: una directory che contiene un file, un file che si trova in quel percorso, o un link. Le directory sopra di essa che non esistono ancora vengono create. Nessun file dell’esempio viene lasciato altrove, e nessuno viene messo al suo posto prima che siano stati scritti tutti: vengono prima scritti a parte e spostati dentro una volta che ci sono tutti.

I comandi che stampa dopo sono quelli indicati dalla pagina stessa dell’esempio: il primo blocco sh, bash o shell sotto l’intestazione ## Build della pagina, così come la pagina lo scrive, commenti inclusi, dopo un cd nella directory. Per un esempio la cui pagina non ha un tale blocco, la risposta è invece il percorso della sua pagina.

Quali esempi ci sono. --list stampa ogni esempio, una volta ciascuno, nell’ordine in cui la documentazione li insegna — il suo nome, il livello che la sua pagina dichiara e la prima frase della sua pagina — e non scrive nulla:

Terminal window
aggrega scaffold --example --list
EXAMPLE 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.
...

L’elenco è l’elenco degli esempi della documentazione stessa, quello pubblicato accanto a essi come Esempi per prodotto e capacità. Un nome sotto il quale il bundle non contiene alcun esempio viene rifiutato, indicandoti --list, e non viene scritto nulla.

Da dove vengono gli esempi. Vengono letti dal bundle della documentazione — l’archivio firmato della documentazione pubblicata da cui aggrega explain legge le sue spiegazioni passo passo — pubblicato sul registry predefinito del tuo workspace. Il bundle letto è quello pubblicato per la versione di aggrega che stai eseguendo. Se per quella versione non ne è pubblicato nessuno, è il più recente pubblicato per un rilascio precedente, e il comando lo segnala sullo standard error:

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

Una build di aggrega ricavata da alcuni commit successivi a un rilascio — una il cui aggrega version si presenta come 0.9.0-12-g1a2b3c4d — legge la documentazione del rilascio dopo il quale è stata costruita, qui 0.9.0, o di uno precedente dove quella non è pubblicata. Una build ricavata da alcuni commit successivi a un pre-rilascio, come una release candidate — una il cui aggrega version si presenta come 0.9.0-rc.6-4-gc9db2f597 — legge la documentazione di quel pre-rilascio, qui 0.9.0-rc.6, oppure, dove quella non è pubblicata, la più recente pubblicata prima di esso, compreso un pre-rilascio precedente. Qualsiasi altra build legge la documentazione di un pre-rilascio solo quando è essa stessa quel pre-rilascio. Una build che non riporta alcun numero di rilascio legge la documentazione della propria versione, oppure nessuna. aggrega explain sceglie allo stesso modo il bundle da cui legge le sue guide passo passo.

Dove per la tua versione non ne è pubblicato nessuno e il più recente tra i precedenti è in un formato che questa versione di aggrega non legge più — una release candidate eseguita prima che sia pubblicata la sua documentazione, per esempio — il comando rifiuta, dicendo entrambe le cose in una sola frase, e non viene scritto nulla:

[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

Viene verificato prima di essere usato. Il bundle viene scaricato con le stesse impostazioni di rete di ogni altra lettura dal registry, e la sua firma viene controllata rispetto alla policy di firma del tuo workspace per quel registry prima che venga conservato — e di nuovo prima che venga letta una copia già presente sulla macchina, così una copia lasciata entrare dalla policy più permissiva di un altro progetto non viene usata sotto la tua. Un bundle che la tua policy non accetta viene rifiutato, e non viene scritto nulla.

Viene scaricato una volta per macchina. Il bundle è conservato nella cache condivisa da ogni progetto Aggrega sulla macchina — vedi aggrega cache — quindi un secondo esempio, o un secondo progetto, non richiede un secondo download, e aggrega explain legge la stessa copia quando entrambi leggono la stessa versione.

Offline, legge solo ciò che è in cache. In un workspace offline non viene scaricato nulla: un esempio viene scritto da una copia già presente sulla macchina che la tua policy ammette — quella per questa versione, oppure la più recente tra le precedenti in cache — e, se non ce n’è nessuna, il comando rifiuta con il rifiuto offline che dà ogni lettura di rete, indicando come consentire la rete.

Un bundle che contiene qualcosa di inatteso viene rifiutato per intero. Il bundle proviene da un registry, quindi l’estrazione non si fida di nulla della sua struttura: una voce il cui nome finirebbe fuori dalla directory che hai indicato, o fuori dal bundle, e una voce che è un link o qualsiasi cosa diversa da un file o da una directory rifiutano ciascuna l’intero esempio, nominando la voce, e non viene scritto nulla. Un file eseguibile nell’esempio resta eseguibile.

Viene letta la configurazione del workspace. Il registry predefinito e la policy di firma provengono da essa, quindi un file di configurazione che è un link che esce dal workspace blocca la forma con esempio come blocca ogni altro comando che legge la configurazione — vedi il confine del workspace.

Esempi

Abbozza una Release senza nome e leggila nel terminale:

Terminal window
aggrega scaffold release

Abbozza una Recipe direttamente in un file:

Terminal window
aggrega scaffold recipe postgres-helm > postgres-helm.yaml

Verifica cosa devi ancora fornire prima di compilare qualsiasi cosa:

Terminal window
aggrega scaffold component my-service > my-service.yaml
aggrega validate my-service.yaml

Guarda quali esempi eseguibili ci sono, poi scrivine uno in una directory a tua scelta:

Terminal window
aggrega scaffold --example --list
aggrega scaffold --example redis-cache my-cache

Per il ciclo di authoring che questo comando avvia — abbozzare la forma, compilare i segnaposto, convalidare — vedi Scrivere file Aggrega.