Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega scaffold

Rascunhar um documento inicial para um tipo de entidade, ou gravar um exemplo executável em um novo diretório

Sinopse

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

Descrição

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.

Flags

FlagPadrãoDescrição
--examplefalsegrava em um novo diretório o exemplo executável que o argumento nomeia, lido do pacote assinado da documentação
--listfalsecom —example, imprime cada exemplo executável que a documentação publica e não grava nada

O que ele faz

O comando tem duas formas. aggrega scaffold <kind> cria um rascunho de documento inicial a partir do schema de um tipo e o imprime, que é o que esta seção e as três seguintes descrevem. aggrega scaffold --example <name> grava, em vez disso, um dos exemplos executáveis da documentação em um novo diretório — consulte Começar a partir de um exemplo executável.

aggrega scaffold <kind> imprime na saída padrão um documento inicial para um tipo de entidade. O documento contém exatamente os campos que o schema desse tipo exige: apiVersion e kind são preenchidos, porque o schema os fixa, e todo outro valor obrigatório fica como um placeholder para você substituir.

O [name] opcional preenche metadata.name para um tipo cujo schema exige um:

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

O tipo é o token de schema em minúsculas e com hifens — component, aggregate, release, recipe, manifest, feature e os demais. aggrega get-schema --list imprime o conjunto completo, e um token ao qual nenhum schema corresponde é recusado com esse conjunto na mensagem, para que um erro de digitação seja corrigido sem uma segunda consulta.

O que ele devolve e o que não devolve

O documento vem do próprio contrato do tipo e de nada mais. Não é um exemplo trabalhado. Não há namespace, nem categoria, nem valores de label preenchidos para você, nem sugestão comentada do que as pessoas costumam escrever — porque nada disso é algo que o compilador exige. Um catálogo escolhe sua própria nomenclatura, suas próprias categorias e sua própria estrutura de diretórios; o schema decide os campos, e o schema é tudo o que este comando lê. Um documento inicial que adivinhasse o resto ensinaria a você uma regra que não existe.

Gerar o rascunho não escreve nenhum arquivo. O documento vai para a saída padrão, então um redirecionamento decide onde ele vai parar, e nada no disco é substituído sem que você peça:

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

Não é uma entidade pronta, e é isso que um placeholder significa. Um valor obrigatório vazio não é um valor, então executar aggrega validate sobre o documento exatamente como ele saiu o recusa e nomeia de uma vez cada placeholder ainda pendente, cada um com o que aceita — acima, a versão e o tipo de 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

O que cada valor aceita é lido do próprio schema do tipo: os valores que ele aceita onde o schema os lista, uma versão semântica onde ele pede uma e, caso contrário, a própria descrição do campo no schema. Forneça esses valores e o mesmo comando aceita o documento. Nada na sua forma precisa mudar, porque a forma veio do schema.

Um valor é devido mesmo onde o schema o aceitaria vazio. Uma Recipe ou FeatureRecipe gerada carrega capability e implements vazios. O schema deles admite uma string vazia, mas uma vazia não nomeia nenhum provider nem nenhum tipo, então aggrega validate aponta ambos como ainda pendentes até que você os preencha. Essa leitura pertence à validação de um único arquivo de entidade: uma execução sobre o catálogo inteiro, aggrega validate --release e aggrega build não a aplicam. Veja placeholders ainda pendentes para o que ela abrange. Uma Recipe gerada também não declara nenhum dos tipos de entrada dos quais seu schema pede pelo menos um — source, valuesMapping, workload ou artifacts —, porque escolher qual se encaixa cabe a você, então aggrega validate recusa seu spec até que você adicione um.

O mesmo documento a partir de um assistente ou editor

O documento inicial tem os mesmos bytes seja qual for a interface que o solicita. Um assistente de IA conectado por meio de aggrega mcp o obtém como a ferramenta scaffold, que retorna o documento como texto junto com um payload legível por máquina. Um editor que controla aggrega serve o obtém em aggrega/scaffoldEntity. O documento é derivado do schema uma única vez, então o que você gera em um terminal e o que um assistente gera para você são idênticos byte a byte.

Escrever e listar exemplos executáveis está disponível nas mesmas superfícies, com as próprias palavras do comando como nomes de campo. Envie à ferramenta scaffold, ou a aggrega/scaffoldEntity, example em vez de kind para escrever um, dir para nomear o novo diretório relativo à raiz do workspace — ali, um diretório com o nome do exemplo quando você não envia nenhum — e list: true sozinho para receber como resposta todos os exemplos. O exemplo é lido do mesmo pacote, verificado com a mesma política e escrito pela mesma extração, então os arquivos e os próximos comandos são os mesmos que em um terminal, assim como as recusas: um diretório que contém qualquer coisa, uma entrada que sai do diretório ou que é um link, um pacote que sua política não aceita, um workspace offline sem nada em cache. A resposta é estruturada: para uma lista, examples, cada um com seu name, level e summary; para uma escrita, example, dir, files — os arquivos escritos, relativos a dir —, next, os comandos que a página do exemplo indica, e version, a versão da documentação da qual o exemplo foi lido. A resposta da ferramenta scaffold a uma escrita também traz output_dir, onde o diretório está — completo via entrada e saída padrão, para que um assistente que o nomeou relativo a um workspace que não consegue ver leia para onde o exemplo foi, e relativo à raiz do workspace via HTTP. O texto da ferramenta scaffold é o relato que este comando imprime, encerrado por uma linha que nomeia esse local quando ele difere de dir. Campos de duas formas enviados juntos — kind com example, por exemplo — são recusados com as mesmas palavras em ambas as superfícies, antes que qualquer coisa seja lida. Um editor nomeia o workspace no workspaceRoot da solicitação para a forma de exemplo, e dir deve ser um caminho relativo que permaneça dentro dele e não saia dele por meio de um link; via HTTP, a ferramenta também prende dir ao workspace que atende, e via entrada e saída padrão ela aceita dir como nomeado, como aceita qualquer caminho. O índice de capacidades informa que a ferramenta scaffold escreve, por causa dessa forma, e que cli-scaffold, que executa este comando em um processo separado, também escreve.

Começar a partir de um exemplo executável

A documentação traz exemplos executáveis — cada um é um diretório que contém um Aggregate, suas Releases e tudo o mais a partir do que ele é construído, com uma página dizendo como construí-lo. --example escreve um deles em um novo diretório, para que você possa começar de um projeto que funciona em vez de um em branco:

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.

O que ele escreve, e onde. Os arquivos do exemplo, como a documentação os traz, no diretório que você nomeia como segundo argumento — ou, quando você não nomeia nenhum, em um diretório com o nome do exemplo na pasta em que você executa o comando. O diretório ainda não deve existir, ou deve estar vazio. Qualquer outra coisa é recusada e deixada exatamente como estava: um diretório que contém um arquivo, um arquivo nesse caminho ou um link. Diretórios acima dele que ainda não existem são criados. Nenhum arquivo do exemplo é deixado em outro lugar, e nenhum é colocado no lugar antes que todos sejam escritos: eles são escritos à parte primeiro e movidos para dentro assim que todos estiverem lá.

Os comandos que ele imprime em seguida são os que a própria página do exemplo indica: o primeiro bloco sh, bash ou shell sob o título ## Build da página, como a página o escreve, incluindo os comentários, depois de um cd para o diretório. Um exemplo cuja página não tem esse bloco recebe como resposta, em vez disso, o caminho da sua página.

Quais exemplos existem. --list imprime cada exemplo, uma vez cada, na ordem em que a documentação os ensina — seu nome, o nível que sua página declara e a primeira frase da sua página — e não escreve nada:

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.
...

A lista é a própria lista de exemplos da documentação, a que é publicada ao lado deles como Exemplos por produto e capacidade. Um nome sob o qual o pacote não traz nenhum exemplo é recusado, indicando --list, e nada é escrito.

De onde vêm os exemplos. Eles são lidos do pacote de documentação — o arquivo assinado da documentação publicada do qual aggrega explain lê seus passo a passo — publicado no registro padrão do seu workspace. O pacote lido é o publicado para a versão do aggrega que você está executando. Quando nenhum é publicado para essa versão, é o mais recente publicado para uma versão anterior, e o comando informa isso na saída de erro padrão:

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

Um build do aggrega feito a partir de alguns commits após uma versão publicada — um cujo aggrega version se lê como 0.9.0-12-g1a2b3c4d — lê a documentação da versão depois da qual foi construído, aqui 0.9.0, ou de uma anterior quando essa não está publicada. Um build feito a partir de alguns commits após uma pré-versão, como uma versão candidata — um cujo aggrega version se lê como 0.9.0-rc.6-4-gc9db2f597 — lê a documentação dessa pré-versão, aqui 0.9.0-rc.6, ou, quando essa não está publicada, da mais recente publicada antes dela, incluindo uma pré-versão anterior. Qualquer outro build lê a documentação de uma pré-versão somente quando é essa própria pré-versão. Um build que não traz nenhum número de versão lê a documentação da sua própria versão ou nenhuma. aggrega explain escolhe da mesma forma o pacote do qual lê as suas explicações passo a passo.

Quando nenhum é publicado para a sua versão e o mais recente dos anteriores está em um formato que esta versão do aggrega não lê mais — uma versão candidata executada antes de sua própria documentação ser publicada, por exemplo —, o comando recusa, dizendo as duas coisas em uma única frase, e nada é gravado:

[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

Ele é verificado antes de ser usado. O pacote é obtido com as mesmas configurações de rede de qualquer outra leitura de registro, e sua assinatura é verificada em relação à política de assinaturas do seu workspace para esse registro antes de ser guardado — e de novo antes que uma cópia já presente na máquina seja lida, de modo que uma cópia admitida pela política mais branda de outro projeto não é usada sob a sua. Um pacote que sua política não aceita é recusado, e nada é escrito.

Ele é obtido uma vez por máquina. O pacote é mantido no cache que todo projeto Aggrega na máquina compartilha — veja aggrega cache —, então um segundo exemplo, ou um segundo projeto, não precisa de um segundo download, e aggrega explain lê a mesma cópia quando ambos leem a mesma versão.

Offline, ele lê apenas o que está em cache. Em um workspace offline nada é obtido: um exemplo é escrito a partir de uma cópia já presente na máquina que sua política admite — a desta versão ou, senão, a mais recente anterior em cache — e, sem nenhuma, o comando recusa com a recusa offline que toda leitura de rede dá, indicando como permitir a rede.

Um pacote que traz algo inesperado é recusado por inteiro. O pacote vem de um registro, então a extração não confia em nada do seu layout: uma entrada cujo nome iria parar fora do diretório que você nomeou, ou fora do pacote, e uma entrada que é um link ou qualquer coisa além de um arquivo ou diretório recusam, cada uma, o exemplo inteiro, nomeando a entrada, e nada é escrito. Um arquivo executável no exemplo continua executável.

A configuração do workspace é lida. O registro padrão e a política de assinaturas vêm dela, então um arquivo de configuração que é um link que sai do workspace interrompe a forma de exemplo como interrompe qualquer outro comando que lê a configuração — veja o limite do workspace.

Exemplos

Gere uma Release sem nome e leia-a no terminal:

Terminal window
aggrega scaffold release

Gere uma Recipe diretamente em um arquivo:

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

Verifique o que você ainda deve antes de preencher qualquer coisa:

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

Veja quais exemplos executáveis existem e depois escreva um em um diretório de sua escolha:

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

Para o ciclo de autoria que este comando inicia — gerar a forma, preencher os placeholders, validar —, veja Escrever arquivos do Aggrega.