aggrega scaffold
Redactar un documento inicial para un tipo de entidad, o escribir un ejemplo ejecutable en un directorio nuevo
Sinopsis
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]Descripción
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 | Predeterminado | Descripción |
|---|---|---|
--example | false | escribe en un directorio nuevo el ejemplo ejecutable que nombra el argumento, leído del paquete firmado de la documentación |
--list | false | con —example, imprime cada ejemplo ejecutable que publica la documentación y no escribe nada |
Qué hace
El comando tiene dos formas. aggrega scaffold <kind> redacta un documento inicial a partir del esquema de un tipo y lo imprime, que es lo que describen esta sección y las tres siguientes. aggrega scaffold --example <name> escribe en cambio uno de los ejemplos ejecutables de la documentación en un directorio nuevo — consulta Empezar desde un ejemplo ejecutable.
aggrega scaffold <kind> imprime en la salida estándar un documento inicial para un tipo de entidad. El documento lleva exactamente los campos que exige el esquema de ese tipo: apiVersion y kind están rellenados, porque el esquema los fija, y cualquier otro valor obligatorio se deja como marcador de posición para que lo sustituyas.
El [name] opcional rellena previamente metadata.name para un tipo cuyo esquema lo exige:
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}El tipo es el token de esquema en minúsculas y con guiones: component, aggregate, release, recipe, manifest, feature y los demás. aggrega get-schema --list imprime el conjunto completo, y un token al que no corresponde ningún esquema se rechaza con ese conjunto en el mensaje, de modo que una errata se corrige sin una segunda consulta.
Lo que devuelve y lo que no
El documento procede del propio contrato del tipo y de nada más. No es un ejemplo desarrollado. No hay namespace, ni categoría, ni valores de etiqueta rellenados por ti, ni sugerencias comentadas de lo que se suele escribir, porque nada de eso es algo que exija el compilador. Un catálogo elige su propia nomenclatura, sus propias categorías y su propia estructura de directorios; el esquema decide los campos, y el esquema es todo lo que lee este comando. Un documento inicial que adivinara el resto te enseñaría una regla que no existe.
Generar el borrador no escribe ningún archivo. El documento va a la salida estándar, de modo que una redirección decide dónde acaba y nada en el disco se sustituye sin que lo pidas:
aggrega scaffold component my-service > my-service.yamlNo es una entidad terminada, y eso es lo que significa un marcador de posición. Un valor obligatorio vacío no es un valor, así que ejecutar aggrega validate sobre el documento tal como salió lo rechaza y nombra de una vez cada marcador de posición aún pendiente, cada uno con lo que admite; arriba, la versión y el 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, resourceLo que admite cada valor se lee del propio esquema del tipo: los valores que acepta donde el esquema los enumera, una versión semántica donde pide una y, en otro caso, la propia descripción del campo en el esquema. Proporciona esos valores y el mismo comando acepta el documento. Nada de su forma tiene que cambiar, porque la forma procede del esquema.
Un valor está pendiente incluso donde el esquema lo aceptaría vacío. Una Recipe o FeatureRecipe generada lleva capability e implements vacíos. Su esquema admite una cadena vacía, pero una vacía no nombra ningún provider ni ningún tipo, así que aggrega validate indica ambos como aún pendientes hasta que los rellenes. Esa lectura corresponde a validar un único archivo de entidad: una ejecución sobre todo el catálogo, aggrega validate --release y aggrega build no la aplican. Consulta marcadores de posición aún pendientes para ver lo que abarca. Una Recipe generada tampoco declara ninguno de los tipos de entrada de los que su esquema pide al menos uno —source, valuesMapping, workload o artifacts—, porque elegir cuál encaja te corresponde a ti, así que aggrega validate rechaza su spec hasta que añadas uno.
El mismo documento desde un asistente o un editor
El documento inicial tiene los mismos bytes sea cual sea la superficie que lo pida. Un asistente de IA conectado mediante aggrega mcp lo obtiene como la herramienta scaffold, que devuelve el documento como texto junto con una carga útil legible por máquina. Un editor que controla aggrega serve lo obtiene en aggrega/scaffoldEntity. El documento se deriva del esquema una sola vez, de modo que el que generas en un terminal y el que un asistente genera para ti son idénticos byte a byte.
Escribir y listar ejemplos ejecutables está disponible en las mismas superficies, con las palabras del propio comando como nombres de campo. Envía a la herramienta scaffold, o a aggrega/scaffoldEntity, example en lugar de kind para escribir uno, dir para nombrar el nuevo directorio relativo a la raíz del espacio de trabajo — allí, un directorio con el nombre del ejemplo cuando no envías ninguno — y list: true solo para recibir como respuesta todos los ejemplos. El ejemplo se lee del mismo paquete, se verifica con la misma política y se escribe con la misma extracción, así que los archivos y los comandos siguientes son los mismos que en un terminal, y también lo son los rechazos: un directorio que contiene algo, una entrada que sale del directorio o que es un enlace, un paquete que tu política no acepta, un espacio de trabajo sin conexión sin nada en caché. La respuesta es estructurada: para una lista, examples, cada uno con su name, level y summary; para una escritura, example, dir, files — los archivos escritos, relativos a dir —, next, los comandos que da la página del ejemplo, y version, la versión de la documentación de la que se leyó el ejemplo. La respuesta de la herramienta scaffold a una escritura también lleva output_dir, dónde está el directorio — completo por la entrada y salida estándar, para que un asistente que lo nombró relativo a un espacio de trabajo que no puede ver lea adónde fue el ejemplo, y relativo a la raíz del espacio de trabajo por HTTP. El texto de la herramienta scaffold es el resumen que imprime este comando, cerrado por una línea que nombra esa ubicación cuando difiere de dir. Los campos de dos formas enviados juntos — kind con example, por ejemplo — se rechazan con las mismas palabras en ambas superficies, antes de leer nada. Un editor nombra el espacio de trabajo en el workspaceRoot de la solicitud para la forma de ejemplo, y dir debe ser una ruta relativa que se quede dentro de él y no salga de él a través de un enlace; por HTTP, la herramienta también ciñe dir al espacio de trabajo que sirve, y por la entrada y salida estándar toma dir tal como se nombra, igual que toma cualquier ruta. El índice de capacidades indica que la herramienta scaffold escribe, debido a esa forma, y que cli-scaffold, que ejecuta este comando en un proceso aparte, también escribe.
Empezar desde un ejemplo ejecutable
La documentación incluye ejemplos ejecutables — cada uno es un directorio que contiene un Aggregate, sus Releases y todo lo demás a partir de lo que se construye, con una página que explica cómo construirlo. --example escribe uno de ellos en un directorio nuevo, para que puedas empezar desde un proyecto que funciona en lugar de desde uno vacío:
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.Qué escribe y dónde. Los archivos del ejemplo, tal como los incluye la documentación, en el directorio que nombras como segundo argumento — o, si no nombras ninguno, en un directorio con el nombre del ejemplo en la carpeta desde la que ejecutas el comando. El directorio no debe existir todavía, o debe estar vacío. Cualquier otra cosa se rechaza y se deja exactamente como estaba: un directorio que contiene un archivo, un archivo situado en esa ruta o un enlace. Los directorios por encima de él que aún no existen se crean. Ningún archivo del ejemplo queda en ningún otro lugar, y ninguno se coloca en su sitio antes de que se hayan escrito todos: primero se escriben aparte y se mueven dentro una vez que están todos.
Los comandos que imprime a continuación son los que da la propia página del ejemplo: el primer bloque sh, bash o shell bajo el encabezado ## Build de la página, tal como la página lo escribe, con los comentarios incluidos, después de un cd al directorio. A un ejemplo cuya página no tiene un bloque así se le responde en su lugar con la ruta de su página.
Qué ejemplos hay. --list imprime cada ejemplo, una vez cada uno, en el orden en que los enseña la documentación — su nombre, el nivel que declara su página y la primera frase de su página — y no escribe 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....La lista es la propia lista de ejemplos de la documentación, la que se publica junto a ellos como Ejemplos por producto y capacidad. Un nombre bajo el que el paquete no incluye ningún ejemplo se rechaza, remitiéndote a --list, y no se escribe nada.
De dónde vienen los ejemplos. Se leen del paquete de documentación — el archivo firmado de la documentación publicada del que aggrega explain lee sus explicaciones paso a paso — publicado en el registro predeterminado de tu espacio de trabajo. El paquete que se lee es el publicado para la versión de aggrega que estás ejecutando. Si no hay ninguno publicado para esa versión, es el más reciente publicado para una versión anterior, y el comando lo indica en la salida de error estándar:
note: no documentation is published for 0.9.1; the examples are read from the documentation published for 0.9.0, the newest before itUna compilación de aggrega hecha a partir de algunos commits posteriores a una versión publicada — una cuyo aggrega version se lee como 0.9.0-12-g1a2b3c4d — lee la documentación de la versión tras la que se compiló, aquí 0.9.0, o la de una anterior donde esa no está publicada. Una compilación hecha a partir de algunos commits posteriores a una versión preliminar, como una versión candidata — una cuyo aggrega version se lee como 0.9.0-rc.6-4-gc9db2f597 — lee la documentación de esa versión preliminar, aquí 0.9.0-rc.6, o, donde esa no está publicada, la más reciente publicada antes de ella, incluida una versión preliminar anterior. Cualquier otra compilación lee la documentación de una versión preliminar solo cuando es esa misma versión preliminar. Una compilación que no lleva ningún número de versión lee la documentación de su propia versión o ninguna. aggrega explain elige del mismo modo el paquete del que lee sus explicaciones paso a paso.
Cuando no hay ninguno publicado para tu versión y el más reciente de los anteriores está en un formato que esta versión de aggrega ya no lee —una versión candidata ejecutada antes de que se publique su propia documentación, por ejemplo—, el comando se niega, diciendo ambas cosas en una sola frase, y no se escribe nada:
[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 readSe verifica antes de usarse. El paquete se descarga con la misma configuración de red que cualquier otra lectura del registro, y su firma se comprueba con la política de firmas de tu espacio de trabajo para ese registro antes de conservarlo — y de nuevo antes de leer una copia que ya está en la máquina, de modo que una copia que admitió la política más laxa de otro proyecto no se usa bajo la tuya. Un paquete que tu política no acepta se rechaza, y no se escribe nada.
Se descarga una vez por máquina. El paquete se guarda en la caché que comparten todos los proyectos de Aggrega de la máquina — consulta aggrega cache —, así que un segundo ejemplo, o un segundo proyecto, no necesita una segunda descarga, y aggrega explain lee la misma copia cuando ambos leen la misma versión.
Sin conexión, solo lee lo que está en caché. En un espacio de trabajo sin conexión no se descarga nada: un ejemplo se escribe a partir de una copia que ya está en la máquina y que tu política admite — la de esta versión o, si no, la más reciente de las anteriores en caché — y, si no hay ninguna, el comando se niega con el rechazo sin conexión que da toda lectura de red, indicando cómo permitir la red.
Un paquete que trae algo inesperado se rechaza entero. El paquete viene de un registro, así que la extracción no confía en nada de su estructura: una entrada cuyo nombre iría a parar fuera del directorio que nombraste, o fuera del paquete, y una entrada que es un enlace o cualquier cosa distinta de un archivo o un directorio rechazan cada una el ejemplo entero, nombrando la entrada, y no se escribe nada. Un archivo ejecutable del ejemplo sigue siendo ejecutable.
Se lee la configuración del espacio de trabajo. El registro predeterminado y la política de firmas salen de ella, así que un archivo de configuración que es un enlace que sale del espacio de trabajo detiene la forma de ejemplo igual que detiene cualquier otro comando que lee la configuración — consulta el límite del espacio de trabajo.
Ejemplos
Genera una Release sin nombre y léela en el terminal:
aggrega scaffold releaseGenera una Recipe directamente en un archivo:
aggrega scaffold recipe postgres-helm > postgres-helm.yamlComprueba lo que aún te falta antes de rellenar nada:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yamlMira qué ejemplos ejecutables hay y luego escribe uno en el directorio que elijas:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cachePara el ciclo de autoría que inicia este comando —generar la forma, rellenar los marcadores de posición, validar—, consulta Escribir archivos de Aggrega.