aggrega scaffold
Rascunhar um documento inicial para um tipo de entidade, ou escrever um exemplo executável num 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
| Flag | Predefinição | Descrição |
|---|---|---|
--example | false | escreve num novo diretório o exemplo executável que o argumento indica, lido do pacote assinado da documentação |
--list | false | com —example, imprime cada exemplo executável que a documentação publica, e não escreve nada |
O que faz
O comando tem duas formas. aggrega scaffold <kind> redige um documento inicial a partir do esquema de um tipo e imprime-o, que é o que esta secção e as três seguintes descrevem. aggrega scaffold --example <name> escreve, em vez disso, um dos exemplos executáveis da documentação num novo diretório — consulte-se 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 esquema desse tipo exige: apiVersion e kind são preenchidos, porque o esquema os fixa, e todos os outros valores obrigatórios ficam como marcadores de posição para o utilizador substituir.
O [name] opcional preenche metadata.name para um tipo cujo esquema exige um:
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}O tipo é o token de esquema em minúsculas com hífenes — component, aggregate, release, recipe, manifest, feature e os restantes. aggrega get-schema --list imprime o conjunto completo, e um token a que nenhum esquema corresponda é recusado com esse conjunto na mensagem, pelo que um erro de digitação é corrigido sem uma segunda consulta.
O que devolve, e o que não devolve
O documento vem do próprio contrato do tipo e de mais nada. Não é um exemplo trabalhado. Não há espaço de nomes, categoria nem valores de etiquetas preenchidos pelo utilizador, nem sugestões comentadas do que as pessoas costumam escrever — porque nada disso é algo que o compilador exija. Um catálogo escolhe a sua própria nomenclatura, as suas próprias categorias e a sua própria disposição de diretórios; o esquema decide os campos, e o esquema é tudo o que este comando lê. Um documento inicial que adivinhasse o resto ensinaria uma regra que não existe.
Gerar o rascunho não escreve nenhum ficheiro. O documento vai para a saída padrão, pelo que um redirecionamento decide onde fica e nada no disco é substituído sem que o utilizador o peça:
aggrega scaffold component my-service > my-service.yamlNão é uma entidade terminada, e é isso que significa um marcador de posição. Um valor obrigatório vazio não é um valor, pelo que executar aggrega validate sobre o documento exatamente como saiu recusa-o e nomeia de uma só vez todos os marcadores de posição ainda em falta, cada um com o que aceita — acima, a versão e o tipo de componente:
Entity: my-service.yamlKind: 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, resourceO que cada valor aceita é lido do próprio esquema do tipo: os valores que aceita onde o esquema os lista, uma versão semântica onde pede uma e, caso contrário, a própria descrição do campo no esquema. Forneça esses valores e o mesmo comando aceita o documento. Nada na sua forma tem de mudar, porque a forma veio do esquema.
Um valor está em falta mesmo onde o esquema o aceitaria vazio. Uma Recipe ou FeatureRecipe gerada tem capability e implements vazios. O seu esquema admite uma cadeia vazia, mas uma vazia não nomeia nenhum provider nem nenhum tipo, pelo que aggrega validate nomeia ambos como ainda em falta até serem preenchidos. Essa leitura é própria da validação de um único ficheiro de entidade: uma execução sobre todo o catálogo, aggrega validate --release e aggrega build não a aplicam. Consulte marcadores de posição ainda em falta para o que abrange. Uma Recipe gerada também não declara nenhum dos tipos de entrada dos quais o seu esquema pede pelo menos um — source, valuesMapping, workload ou artifacts — porque a escolha do que se adequa cabe ao autor, pelo que aggrega validate recusa o seu spec até ser acrescentado um.
O mesmo documento a partir de um assistente ou de um editor
O documento inicial é composto pelos mesmos bytes, seja qual for a superfície que o pede. Um assistente de IA ligado através de aggrega mcp obtém-no através da ferramenta scaffold, que devolve o documento como texto juntamente com um conteúdo legível por máquina. Um editor que controle aggrega serve obtém-no em aggrega/scaffoldEntity. O documento é derivado do esquema uma única vez, pelo que o que é gerado num terminal e o que um assistente gera para o utilizador 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 espaço de trabalho — aí, um diretório com o nome do exemplo quando não se envia nenhum — e list: true sozinho para receber em resposta todos os exemplos. O exemplo é lido do mesmo pacote, verificado segundo a mesma política e escrito pela mesma extração, pelo que os ficheiros e os comandos seguintes são os mesmos que num terminal, tal como as recusas: um diretório que contenha alguma coisa, uma entrada que conduza para fora do diretório ou que seja uma ligação, um pacote que a política não aceite, um espaço de trabalho offline sem nada em cache. A resposta é estruturada: para uma lista, examples, cada um com o seu name, level e summary; para uma escrita, example, dir, files — os ficheiros escritos, relativos a dir —, next, os comandos que a página do exemplo indica, e version, a versão da documentação a partir da qual o exemplo foi lido. A resposta da ferramenta scaffold a uma escrita também inclui output_dir, onde fica o diretório — completo por entrada e saída padrão, para que um assistente que o nomeou relativamente a um espaço de trabalho que não consegue ver leia para onde foi o exemplo, e relativo à raiz do espaço de trabalho por HTTP. O texto da ferramenta scaffold é o relato que este comando imprime, terminado por uma linha que indica essa localização quando difere de dir. Campos de duas formas enviados em conjunto — kind com example, por exemplo — são recusados com as mesmas palavras em ambas as superfícies, antes de qualquer leitura. Um editor nomeia o espaço de trabalho no workspaceRoot do pedido para a forma de exemplo, e dir tem de ser um caminho relativo que fique dentro dele e não conduza para fora dele através de uma ligação; por HTTP, a ferramenta também vincula dir ao espaço de trabalho que serve, e por entrada e saída padrão aceita dir tal como é nomeado, como aceita qualquer caminho. O índice de capacidades indica que a ferramenta scaffold escreve, por causa dessa forma, e que cli-scaffold, que executa este comando num processo separado, também escreve.
Começar a partir de um exemplo executável
A documentação inclui exemplos executáveis — cada um é um diretório que contém um Aggregate, as suas Releases e tudo o resto a partir do qual é construído, com uma página que diz como construí-lo. --example escreve um deles num novo diretório, para que se possa começar a partir de um projeto que funciona em vez de um projeto vazio:
aggrega scaffold --example redis-cacheWrote 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 escreve, e onde. Os ficheiros do exemplo, tal como a documentação os inclui, no diretório nomeado como segundo argumento — ou, quando não se nomeia nenhum, num diretório com o nome do exemplo na pasta em que o comando é executado. O diretório ainda não pode existir, ou tem de estar vazio. Qualquer outra coisa é recusada e deixada exatamente como estava: um diretório que contenha um ficheiro, um ficheiro nesse caminho ou uma ligação. Os diretórios acima dele que ainda não existam são criados. Nenhum ficheiro do exemplo é deixado noutro sítio, e nenhum é colocado no lugar antes de todos estarem escritos: são primeiro escritos à parte e movidos para dentro assim que todos lá estiverem.
Os comandos que imprime a seguir 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, tal 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 tenha esse bloco recebe como resposta, em vez disso, o caminho da sua página.
Que exemplos existem. --list imprime cada exemplo, uma vez cada, pela ordem em que a documentação os ensina — o seu nome, o nível que a sua página declara e a primeira frase da sua página — e não escreve nada:
aggrega scaffold --example --listEXAMPLE 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 junto deles como Exemplos por produto e capacidade. Um nome sob o qual o pacote não inclua nenhum exemplo é recusado, remetendo para --list, e nada é escrito.
De onde vêm os exemplos. São lidos do pacote da documentação — o arquivo assinado da documentação publicada a partir do qual aggrega explain lê as suas explicações passo a passo — publicado no registo predefinido do espaço de trabalho. O pacote lido é o publicado para a versão do aggrega em execução. Quando nenhum está publicado para essa versão, é o mais recente publicado para uma versão anterior, e o comando indica-o 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 itUma compilação do aggrega feita a partir de alguns commits posteriores a uma versão publicada — uma cujo aggrega version se lê como 0.9.0-12-g1a2b3c4d — lê a documentação da versão após a qual foi construída, aqui 0.9.0, ou a de uma anterior quando essa não está publicada. Uma compilação feita a partir de alguns commits posteriores a uma pré-versão, como uma versão candidata — uma 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, a da mais recente publicada antes dela, incluindo uma pré-versão anterior. Qualquer outra compilação só lê a documentação de uma pré-versão quando é essa mesma pré-versão. Uma compilação que não tenha nenhum número de versão lê a documentação da sua própria versão ou nenhuma. O aggrega explain escolhe da mesma forma o pacote a partir do qual lê as suas explicações passo a passo.
Quando não existe nenhum publicado para a sua versão e o mais recente dos anteriores está num formato que esta versão do aggrega já não lê — uma versão candidata executada antes de a sua própria documentação ser publicada, por exemplo —, o comando recusa, dizendo ambas as coisas numa só frase, e nada é escrito:
[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É verificado antes de ser usado. O pacote é obtido com as mesmas definições de rede de qualquer outra leitura do registo, e a sua assinatura é verificada segundo a política de assinaturas do espaço de trabalho para esse registo antes de ser guardado — e novamente antes de ser lida uma cópia já presente na máquina, pelo que uma cópia admitida pela política mais permissiva de outro projeto não é usada sob a sua. Um pacote que a política não aceite é recusado, e nada é escrito.
É obtido uma vez por máquina. O pacote é mantido na cache que todos os projetos Aggrega da máquina partilham — consulte aggrega cache — pelo que um segundo exemplo, ou um segundo projeto, não precisa de uma segunda transferência, e aggrega explain lê a mesma cópia quando ambos leem a mesma versão.
Offline, lê apenas o que está em cache. Num espaço de trabalho offline nada é obtido: um exemplo é escrito a partir de uma cópia já presente na máquina que a política admita — a desta versão ou, caso contrário, a mais recente anterior em cache — e, sem nenhuma, o comando recusa com a recusa offline que todas as leituras de rede dão, indicando como permitir a rede.
Um pacote que contenha algo inesperado é recusado por inteiro. O pacote vem de um registo, pelo que a extração não confia em nada da sua estrutura: uma entrada cujo nome fosse parar fora do diretório nomeado, ou fora do pacote, e uma entrada que seja uma ligação ou qualquer coisa que não um ficheiro ou um diretório recusam cada uma o exemplo inteiro, nomeando a entrada, e nada é escrito. Um ficheiro executável no exemplo continua executável.
A configuração do espaço de trabalho é lida. O registo predefinido e a política de assinaturas vêm dela, pelo que um ficheiro de configuração que seja uma ligação que conduza para fora do espaço de trabalho interrompe a forma de exemplo tal como interrompe qualquer outro comando que leia a configuração — consulte o limite do espaço de trabalho.
Exemplos
Gerar uma Release sem nome e lê-la no terminal:
aggrega scaffold releaseGerar uma Recipe diretamente para um ficheiro:
aggrega scaffold recipe postgres-helm > postgres-helm.yamlVerificar o que ainda falta antes de preencher o que quer que seja:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlVeja que exemplos executáveis existem e depois escreva um num diretório à sua escolha:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cachePara o ciclo de autoria que este comando inicia — gerar a forma, preencher os marcadores de posição, validar — consulte Escrever ficheiros do Aggrega.