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

Visão geral da CLI

A CLI aggrega é o ponto de entrada do compilador. Todas as interações com o Aggrega — compilar um Aggregate em artefactos implementáveis, inspecionar o catálogo ou o IR, resolver e fixar dependências, publicar entidades de catálogo, verificar a correção com validate, verificar as convenções de publicação com lint e servir um IDE — passam por um subcomando de aggrega. Este conjunto de capítulos aborda as flags, entradas e saídas de cada subcomando.

aggrega validate e aggrega lint são verificadores complementares que espelham os três âmbitos um do outro — todo o catálogo, o fecho de dependências de uma Release ou uma entidade. aggrega validate verifica a correção (esquema, pilares, resolução de referências, extends, capacidade de tipos de entrada do provider e — para uma entidade de renderização — uma renderização isolada); aggrega lint verifica as convenções de publicação (nomenclatura, alinhamento com o diretório de categoria, prefixos de anotações e dimensão do incremento de versão). Nenhum deles emite artefactos; use validate para responder a «isto está correto?» e lint para responder a «isto segue a disciplina de publicação do catálogo?».

aggrega build segue o princípio do ponto de entrada único: a Release é a única entrada de compilação. aggrega build --release release.yaml lê os ponteiros aggregate: e manifest: da Release para localizar o resto da topologia, e produz saída por fronteira em dist/: uma fronteira com nome é renderizada no directory: que declara, ou em dist/boundaries/<boundary-name>/ quando não declara nenhum; uma Release que declare components: de nível superior em vez de fronteiras com nome é renderizada de forma plana em dist/. Todos os componentes que a topologia contém têm de pertencer a uma dessas fronteiras, e um componente que nenhuma delas contenha interrompe o build: um componente chega a uma fronteira ou por ser nomeado sob os components: dessa fronteira, com o ID que tem depois de os sub-Aggregates serem achatados, ou por estar dentro de um sub-Aggregate que a fronteira encaminha sob aggregates:. Um componente que não chegue a nenhuma seria renderizado fora de todas as fronteiras que a Release declara, sem obter de lado nenhum a sua localização de saída, onda de sincronização, anotações e infra: por componente, pelo que o build para e nomeia o componente em vez de emitir artefactos aos quais a configuração de fronteiras da Release nunca foi aplicada. A mesma relação é verificada do lado da Release: uma entrada de fronteira que nomeie um componente que a topologia não contém não configura nada, pelo que também interrompe o build e o diagnóstico indica o ID a que a entrada se dirigia. aggrega pull partilha a forma da Release como entrada; aggrega inspect recebe qualquer entidade — um nome de catálogo, um ficheiro de entidade, uma referência de registo ou uma Release; aggrega push recebe uma entidade de catálogo; aggrega validate e aggrega lint aceitam uma entidade de catálogo, uma Release (via --release) ou todo o catálogo; aggrega serve corre como processo de longa duração. A página de flags globais documenta as flags que se aplicam a todos os subcomandos.

O que uma versão pode alterar nos comandos, nas opções e nas ferramentas do assistente — e o que uma versão de correção nunca altera — está indicado em Compatibilidade.

Referência por comando

  • aggrega build — o comando de compilação principal. Lê um ponteiro de Release, resolve o Aggregate e o Manifest que referencia e emite artefactos compilados por fronteira.
  • aggrega inspect — uma vista legível de qualquer entidade: uma entidade de catálogo pelo nome, um ficheiro de entidade pelo caminho, uma entidade publicada lida diretamente do seu registo ou uma Release totalmente resolvida, cujo grafo IR --ir-graph escreve em JSON e cujo fecho de dependências --closure reporta.
  • aggrega pull — resolve as dependências de uma Release e escreve um lockfile por Release que fixa todas as dependências; guarda em cache entidades de catálogo e artefactos de origem.
  • aggrega push — publica uma entidade de catálogo num registo OCI, assinando-a opcionalmente no momento do push.
  • aggrega sign — assina um ou mais artefactos já publicados e anexa cada assinatura como referrer OCI.
  • aggrega auth token — obtém interativamente um token de identidade OIDC e imprime-o no stdout, para uma única autenticação num lote de assinaturas keyless.
  • aggrega registry — gere os registos que o workspace conhece e a sua política de confiança de assinaturas: acrescenta, lista e remove entradas, e constrói um índice local pesquisável dos metadados de catálogo publicados com registry update.
  • aggrega search — pesquisa no índice local dos registos configurados entidades de catálogo publicadas e plugins de CLI instaláveis, fazendo corresponder uma consulta de texto livre e filtros de facetas opcionais.
  • aggrega validate — verifica a correção (esquema, pilares, resolução de referências, extends, capacidade de tipos de entrada, renderização isolada) em todo o catálogo, no fecho de dependências de uma Release (--release) ou numa entidade.
  • aggrega lint — verifica as convenções de publicação em todo o catálogo, no fecho de dependências de uma Release (--release) ou numa entidade; --pre-publish acrescenta a barreira de incremento de versão com conhecimento do registo.
  • aggrega serve — um daemon de compilador como serviço de longa duração (JSON-RPC sobre stdin/stdout) para integração com IDE.
  • aggrega version — imprime a versão da CLI; -o json emite um objeto legível por máquina.
  • aggrega get-schema — imprime o JSON Schema canónico de um tipo de entidade ou de contrato; --list nomeia todos os tipos. A forma autoritativa com base na qual escrever um ficheiro.
  • aggrega scaffold — imprime um documento inicial para um tipo de entidade, derivado do esquema desse tipo: os campos obrigatórios, com os fixos preenchidos e um marcador de posição onde quer que seja necessário um valor. O rascunho não escreve nenhum ficheiro; redirecione a saída para onde quiser. Com --example, escreve em vez disso um dos exemplos executáveis da documentação num novo diretório, e --example --list nomeia-os.
  • aggrega mcp — executa um servidor Model Context Protocol, sobre a entrada e saída padrão ou sobre HTTP, para que um cliente compatível com MCP se torne um assistente de autoria que conhece o Aggrega. Ver Escrever ficheiros do Aggrega.
  • aggrega skills — instala a skill que ensina um assistente de IA a instalar e usar o Aggrega na pasta de skills desse assistente, para um projeto ou, com --global, para todos os projetos do utilizador.
  • aggrega cache — inspeciona e mantém as caches em disco: lista o que contêm, recupera entradas da cache de artefactos que nenhum lockfile referencia, reduz a cache de módulos compilados até um limite de tamanho ou apaga todas as caches.
  • aggrega config — inspeciona e gere a configuração que o Aggrega lê: mostra o que se aplica e que camada decidiu cada definição, cria uma configuração funcional e fixa no workspace as definições críticas para o build.
  • aggrega deprecate — anexa um marcador de descontinuação assinado a um artefacto já publicado.
  • aggrega edit-document — aplica a um documento uma única edição estruturada e delimitada, preservando todos os bytes em que não toca.
  • aggrega explain — explica a condição de interrupção que um código nomeia.
  • aggrega import — transforma a descrição de uma fonte externa em rascunhos de ficheiros de autoria do Aggrega.
  • aggrega login — autentica-se num registo OCI e guarda a credencial que push, pull e lint --pre-publish apresentam.
  • aggrega logout — remove uma credencial de registo guardada.
  • aggrega pin — regista as fixações de conteúdo das entradas externas de uma entidade no entity.lock ao lado dela.
  • aggrega plugin — lista os plugins Wasm que a CLI consegue resolver, adiciona ou remove uma associação do workspace e verifica um guest antes de ser publicado.
  • aggrega push-artifact — publica um artefacto de dados autónomo, como um pacote de documentação, num registo OCI sob o respetivo espaço de nomes docs/.
  • Configuração — a que ficheiro pertence uma definição e como as camadas se combinam. Comece aqui: abre com os dois ficheiros de que a maioria dos projetos precisa e deixa para depois os mecanismos a que um projeto maior recorre.
  • Flags globais — flags partilhadas pelos subcomandos (a raiz do workspace, o ficheiro de configuração global, a saída a cores e a saída simples acessível, e a postura offline). O modo offline também está acessível como definição de configuração e como variável de ambiente — ver Configuração, o esquema de configuração e as variáveis de ambiente.
  • A fronteira do workspace — o que está dentro de um workspace, o que uma ligação simbólica que sai dele faz a cada tipo de caminho, os caminhos que saem de propósito e o que fazer quando um é recusado.
ComandoDescrição
aggrega authGerir a identidade de assinatura
aggrega buildCompilar um Aggregate e uma Release em artefactos nativos do provider em dist/ na raiz do workspace
aggrega cacheInspecionar e manter as caches em disco
aggrega configInspecionar e gerir a configuração do workspace
aggrega deprecateAnexar um marcador de descontinuação assinado a um artefacto já publicado
aggrega edit-documentAplicar uma edição estruturada delimitada a um documento, preservando todos os bytes em que não toca
aggrega explainExplicar a condição de interrupção que um código nomeia
aggrega get-schemaImprimir o JSON Schema de um tipo de entidade ou de contrato
aggrega importConverter a descrição de uma origem externa em ficheiros de autoria Aggrega em rascunho
aggrega inspectInspecionar uma entidade de catálogo pelo nome, um ficheiro de entidade pelo caminho ou uma entidade publicada pela sua referência de registo
aggrega lintVerificar as convenções de publicação do catálogo em todo o catálogo, numa Release ou numa entidade
aggrega loginAutenticar-se num registo OCI e guardar a credencial
aggrega logoutRemover uma credencial de registo guardada
aggrega mcpExecutar um servidor Model Context Protocol sobre a entrada e saída padrão, ou sobre HTTP, para integração com assistentes de IA
aggrega pinRegistar as fixações de conteúdo das entradas externas de uma entidade no entity.lock ao lado dela
aggrega pluginInspecionar os plugins Wasm que a CLI consegue resolver
aggrega pullResolver as dependências de catálogo e de origem para a cache e escrever o lockfile por Release
aggrega pushEmpacotar e publicar uma entidade de catálogo num registo OCI
aggrega push-artifactPublicar um artefacto de dados autónomo (como um pacote de documentação) num registo OCI
aggrega registryGerir registos e a sua política de confiança de assinaturas
aggrega scaffoldRascunhar um documento inicial para um tipo de entidade, ou escrever um exemplo executável num novo diretório
aggrega searchPesquisar o índice local dos registos configurados
aggrega serveCorrer como compilador como serviço de longa duração sobre JSON-RPC 2.0 em stdin/stdout
aggrega signAssinar um ou mais artefactos já publicados e anexar as suas assinaturas
aggrega skillsInstalar a skill do Aggrega num assistente de IA
aggrega validateVerificar a correção em todo o catálogo, numa Release ou numa entidade
aggrega versionImprimir a versão da CLI aggrega

Argumentos posicionais e estado de saída

Todos os comandos recusam um argumento posicional de que não precisam, e reportam essa recusa através de um estado de saída diferente de zero em vez de terminarem como se a invocação fosse válida. A regra abrange os comandos que existem apenas para agrupar subcomandos, em que um nome de subcomando mal escrito chega como um posicional não reconhecido: a ajuda do comando é impressa e o estado de saída é diferente de zero, para que um erro de escrita numa superfície automatizada falhe de forma visível em vez de passar por uma execução bem-sucedida. O aggrega invocado com um comando não reconhecido comporta-se da mesma forma e, além disso, nomeia o comando correspondente mais próximo, quando existe um suficientemente próximo.

Um comando não reconhecido indica também como encontrar um plugin de CLI com esse nome. A resposta vem do índice local do registo predefinido que aggrega registry update constrói e aggrega search lê, pelo que chega de imediato e a palavra mal escrita nunca é enviada a um registo, com ou sem ligação. Quando o índice contém um plugin de CLI com esse nome, a mensagem nomeia o comando aggrega plugin add cli <name> que o instala. Quando o índice não contém nenhum, nomeia a pesquisa que procura um, aggrega search <name> --kind plugin --plugin-type cli. Quando ainda não foi construído nenhum índice, nomeia aggrega plugin add cli <name>, que procura o plugin por esse nome no registo e recusa quando nenhum está publicado. Qualquer um dos dois comandos leva o nome entre aspas para a shell quando é necessário.

Quando os posicionais têm significado, a página de referência de cada comando documenta o que aceita. Um plugin de CLI instalado é a exceção deliberada: o seu comando reserva para si a análise dos argumentos, pelo que todo o vetor de argumentos é encaminhado para o plugin, que é o único analisador dos seus próprios argumentos — e o estado de saída do próprio plugin é o que a invocação devolve.

Progresso, e quanto tempo um comando espera por um registo

Um comando que espera indica aquilo por que está à espera. Sempre que um comando espera por um registo, por uma transferência ou pela primeira compilação de um plugin, mostra esse passo na saída de erro padrão, tal como aggrega build e aggrega pull mostram os seus: num terminal, uma linha que nomeia o passo com um indicador giratório e o tempo decorrido até então, assinalada quando o passo termina e deixada por assinalar quando o passo falhou; num terminal que não consegue redesenhar no lugar, ou com --plain, uma linha por passo à medida que termina, com o respetivo tempo. Quando a saída de erro padrão não é um terminal, nada é mostrado, e nada do que um comando escreve na saída padrão muda em qualquer dos casos. Um passo só é mostrado enquanto o comando está realmente à espera dele, pelo que uma execução servida a partir da cache não mostra nada, e a compilação de um plugin só é mostrada quando demora o suficiente para ser uma compilação real e não uma que estava em cache.

Os comandos que mostram os seus passos desta forma, além do comando de cada plugin de CLI instalado:

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

Nenhum pedido espera indefinidamente por um servidor. Um pedido espera no máximo 30 segundos que o servidor comece a sua resposta depois de o pedido ter sido enviado na totalidade, e no máximo 30 segundos pela parte seguinte de uma resposta que já está a chegar. Um servidor que faz um pedido esperar mais tempo é recusado com E0376, que indica o servidor e a espera. Só a espera é limitada: uma transferência ou um envio que continua a avançar demora o tempo que demorar. Um chart do Helm que o source: de uma Recipe obtém por HTTPS está sujeito apenas à primeira das duas esperas, e a sua expiração é comunicada nas palavras da própria biblioteca de rede, e não com E0376. Um pedido que um comando já repete quando o tempo se esgota — uma leitura durante aggrega registry update, uma escrita durante uma publicação — é repetido antes de a recusa ser comunicada.

O percurso da listagem completa de repositórios de um registo termina em cinco minutos. Alguns registos reúnem todos os repositórios que contêm antes sequer de responderem a um pedido de listagem, pelo que cada página da listagem é aguardada durante todo o tempo que o percurso pode durar, e não durante 30 segundos; uma listagem que não terminou ao fim de cinco minutos é interrompida e recusada com E0377. aggrega plugin add percorre a listagem apenas quando nenhum plugin tem exatamente o nome que recebeu, para encontrar um cujo nome o contenha, pelo que nomear o plugin exatamente nunca fica à espera do percurso.

Um registo que pede para abrandar é aguardado, até o ter pedido durante cinco minutos sem interrupção. Um comando espera o tempo que esse registo pedir, envia-lhe menos pedidos em simultâneo e mostra a espera juntamente com o resto do seu progresso; um registo que durante cinco minutos não responde mais nada além de «abrande» é recusado com E0378. Um registo que pede para abrandar descreve como.

Os três limites são fixos; não existe nenhuma definição que os altere.

Os caminhos escritos e a fronteira do workspace

Um caminho escrito na linha de comandos — um --release, um --catalog, um --output-dir, um ficheiro a validar, analisar com lint, fixar ou publicar, um --workspace-root — é usado para onde leva, dentro ou fora do workspace, através de qualquer ligação pelo caminho. O que o comando lê e escreve depois por conta própria fica confinado ao workspace, seja quem for que o execute: não lê os ficheiros de configuração do workspace, um documento de catálogo, um documento ao lado de uma Release ou o lockfile de uma Release através de uma ligação que saia do workspace, não segue um caminho que uma Release ou um Manifest escreva para fora dele, nem escreve a sua saída, o seu lockfile ou a sua cache através de uma ligação dessas. Um diretório indicado fora do workspace fica confinado da mesma forma quanto ao que está abaixo dele, e uma Release indicada fora do workspace só chega a ficheiros no seu próprio diretório. aggrega edit-document é o único comando cujo caminho escrito também fica confinado: só edita um documento que o workspace contém. A fronteira do workspace enuncia a regra, os caminhos que saem de propósito e a solução para cada recusa.

Pesquisar o índice do catálogo

aggrega search [query] procura entidades publicadas nos registos que o workspace conhece. O [query] opcional é uma subcadeia, sem distinção entre maiúsculas e minúsculas, comparada com o nome e a descrição de cada entidade. Os filtros de facetas restringem o conjunto de resultados:

  • --kind restringe a um ou mais tipos de entidade (component, feature, recipe, featurerecipe, workload, plugin); é repetível e não distingue maiúsculas de minúsculas, e os tipos combinam-se por OU.
  • -l/--selector filtra pelas etiquetas de catálogo da entidade. A categoria é uma etiqueta, não uma flag dedicada: -l component.aggrega.ai/category=datastore.
  • --capability e --plugin-type filtram plugins por uma capacidade ou tipo de socket declarado; --capability é repetível e combina-se por OU.
  • --registry limita a pesquisa a um único registo, por host ou alias amigável; por predefinição, são pesquisados todos os registos configurados.
  • --limit limita o número de resultados.
  • -o/--output seleciona o formato de saída: table (a predefinição, legível por pessoas), json (um array legível por máquina) ou names (identificadores simples, um por linha).

A pesquisa lê sempre o índice local — o instantâneo offline que aggrega registry update constrói e atualiza. Não contacta nenhuma rede nem obtém nada a pedido. Quando o índice não existe, o comando falha e indica que se execute primeiro aggrega registry update. Cada execução imprime no erro padrão uma linha de atualidade «last updated» por registo, para que a saída json e names na saída padrão se mantenha limpa para scripts.

Conclusão automática da shell

aggrega completion <shell> imprime no stdout um script de conclusão automática para bash, zsh, fish ou powershell. O script é gerado a partir da árvore de comandos ativa da CLI no momento em que é executado, pelo que reflete sempre os comandos e as flags do binário que o produziu — não há nenhum ficheiro estático a regenerar à medida que a CLI cresce.

Para experimentar a conclusão automática na sessão atual sem instalar nada, carregue o script diretamente com source:

Terminal window
source <(aggrega completion bash)

Para instalar a conclusão automática de forma permanente, escreva o script no local que a shell lê no arranque.

bash

A conclusão automática do Bash depende do pacote bash-completion; instale-o através do gestor de pacotes do sistema operativo se ainda não estiver 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 a conclusão automática ainda não estiver ativada na shell, ative-a uma vez:

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

Em seguida, escreva o script de conclusão automática num diretório do seu 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

Acrescente o script gerado ao perfil do PowerShell para que seja carregado em todas as sessões:

Terminal window
aggrega completion powershell >> $PROFILE

Inicie uma nova shell para que a conclusão automática instalada tenha efeito.