aggrega scaffold
엔티티 종류의 시작 문서 초안 작성 또는 실행 가능한 예제를 새 디렉터리에 쓰기
개요
aggrega scaffold <kind> [name] | --example <name> [dir] | --example --list [flags]설명
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.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--example | false | 인수가 지정한 실행 가능한 예제를 서명된 문서 번들에서 읽어 새 디렉터리에 기록합니다 |
--list | false | —example과 함께 사용하면 문서가 게시하는 모든 실행 가능한 예제를 출력하고 아무것도 기록하지 않습니다 |
동작
이 명령에는 두 가지 형식이 있습니다. aggrega scaffold <kind>는 종류의 스키마로부터 시작 문서의 초안을 만들어 출력하며, 이 절과 이어지는 세 절에서 이를 설명합니다. aggrega scaffold --example <name>은 대신 문서의 실행 가능한 예제 하나를 새 디렉터리에 기록합니다. 실행 가능한 예제에서 시작하기를 참조하십시오.
aggrega scaffold <kind>는 한 엔티티 종류에 대한 시작 문서를 표준 출력으로 출력합니다. 이 문서에는 해당 종류의 스키마가 요구하는 필드만 정확히 들어 있습니다. apiVersion과 kind는 스키마가 고정하므로 채워져 있으며, 그 밖의 모든 필수 값은 직접 바꿔 넣을 자리 표시자로 남겨 둡니다.
선택 사항인 [name]은 스키마가 metadata.name을 요구하는 종류에 대해 그 값을 미리 채웁니다:
aggrega scaffold component my-serviceapiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-service version: "" labels: component.aggrega.ai/type: ""spec: {}종류는 소문자와 하이픈으로 된 스키마 토큰입니다. component, aggregate, release, recipe, manifest, feature 등이 있습니다. aggrega get-schema --list는 전체 목록을 출력하며, 어떤 스키마에도 해당하지 않는 토큰은 그 목록을 메시지에 담아 거부되므로 오타를 다시 찾아보지 않고도 바로잡을 수 있습니다.
반환하는 것과 반환하지 않는 것
문서는 해당 종류 자체의 계약에서만 나옵니다. 이는 완성된 예제가 아닙니다. 네임스페이스, 카테고리, 레이블 값이 대신 채워지지 않으며, 사람들이 흔히 작성하는 내용을 주석으로 제안하지도 않습니다. 그 어느 것도 컴파일러가 요구하는 것이 아니기 때문입니다. 카탈로그는 자체 명명 방식, 자체 카테고리, 자체 디렉터리 구조를 선택합니다. 필드는 스키마가 결정하며, 이 명령이 읽는 것은 스키마뿐입니다. 나머지를 추측해 채운 시작 문서는 존재하지 않는 규칙을 가르치게 됩니다.
초안 작성은 파일을 쓰지 않습니다. 문서는 표준 출력으로 나가므로 리디렉션으로 저장 위치를 정하며, 요청하지 않는 한 디스크의 어떤 파일도 대체되지 않습니다:
aggrega scaffold component my-service > my-service.yaml완성된 엔티티가 아니며, 자리 표시자란 바로 그런 뜻입니다. 비어 있는 필수 값은 값이 아니므로, 출력된 그대로의 문서에 aggrega validate를 실행하면 문서가 거부되고 아직 채워야 할 모든 자리 표시자가 각각 받는 값과 함께 한꺼번에 표시됩니다. 위의 경우 버전과 컴포넌트 유형입니다:
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, resource각 값이 받는 내용은 해당 종류 자체의 스키마에서 읽어 옵니다. 스키마가 허용 값을 나열한 경우 그 값들을, 시맨틱 버전을 요구하는 경우 시맨틱 버전을, 그 밖의 경우 필드에 대한 스키마 자체의 설명을 보여 줍니다. 그 값들을 채우면 같은 명령이 문서를 받아들입니다. 형태는 스키마에서 나왔으므로 형태를 바꿀 필요는 없습니다.
스키마가 빈 값을 허용하는 경우에도 값을 채워야 합니다. 초안으로 작성된 Recipe나 FeatureRecipe에는 비어 있는 capability와 implements가 들어 있습니다. 해당 스키마는 빈 문자열을 허용하지만, 빈 문자열은 어떤 제공자도 어떤 유형도 가리키지 않으므로 aggrega validate는 채울 때까지 둘 다 아직 채워야 할 값으로 표시합니다. 이 해석은 단일 엔티티 파일을 검증할 때에만 적용됩니다. 카탈로그 전체 실행, aggrega validate --release, aggrega build에는 적용되지 않습니다. 적용 범위는 아직 채워야 할 자리 표시자를 참고하십시오. 또한 초안으로 작성된 Recipe는 스키마가 적어도 하나를 요구하는 입력 종류(source, valuesMapping, workload, artifacts)를 하나도 선언하지 않습니다. 어느 것이 맞는지는 작성자가 선택할 일이기 때문입니다. 따라서 하나를 추가할 때까지 aggrega validate는 그 spec을 거부합니다.
어시스턴트나 에디터에서 받는 동일한 문서
시작 문서는 어느 인터페이스가 요청하든 바이트 단위로 동일합니다. aggrega mcp로 연결된 AI 어시스턴트는 scaffold 도구로 이 문서에 접근하며, 이 도구는 문서를 텍스트로 반환하고 기계가 읽을 수 있는 페이로드도 함께 반환합니다. aggrega serve를 구동하는 에디터는 aggrega/scaffoldEntity에서 이 문서에 접근합니다. 문서는 스키마에서 한 번만 도출되므로, 터미널에서 직접 작성한 초안과 어시스턴트가 대신 작성한 초안은 바이트 단위로 동일합니다.
실행 가능한 예제를 쓰고 나열하는 기능도 같은 인터페이스에서 제공되며, 필드 이름에는 이 명령 자체의 용어를 사용합니다. scaffold 도구 또는 aggrega/scaffoldEntity에 kind 대신 example을 보내면 예제를 하나 쓰고, dir을 보내면 새 디렉터리를 워크스페이스 루트 기준 상대 경로로 지정하며(보내지 않으면 그곳에 예제 이름을 딴 디렉터리가 쓰임), list: true만 보내면 모든 예제를 응답으로 받습니다. 예제는 같은 번들에서 읽고, 같은 정책으로 검증하며, 같은 추출 과정으로 쓰므로, 쓰이는 파일과 다음에 실행할 명령은 터미널에서와 같고 거부되는 경우도 같습니다. 즉 무엇이든 들어 있는 디렉터리, 디렉터리 밖으로 이어지는 항목이나 링크, 정책이 받아들이지 않는 번들, 아무것도 캐시되지 않은 오프라인 워크스페이스입니다. 응답은 구조화되어 있습니다. 목록의 경우 examples이며 각 항목에는 name, level, summary가 있습니다. 쓰기의 경우 example, dir, files(쓴 파일로, dir 기준 상대 경로), next(예제 페이지가 제시하는 명령), version(예제를 읽어 온 문서 버전)입니다. 쓰기에 대한 scaffold 도구의 응답에는 디렉터리 위치인 output_dir도 담깁니다. 표준 입력과 출력을 통해서는 전체 경로로 담기므로, 볼 수 없는 워크스페이스 기준 상대 경로로 지정한 어시스턴트도 예제가 어디에 쓰였는지 알 수 있고, HTTP를 통해서는 워크스페이스 루트 기준 상대 경로로 담깁니다. scaffold 도구의 텍스트는 이 명령이 출력하는 설명이며, 그 위치가 dir과 다를 때는 그 위치를 알려 주는 줄로 끝납니다. 두 형식의 필드를 함께 보내면(예: kind와 example) 무엇이든 읽기 전에 두 인터페이스 모두에서 같은 문구로 거부됩니다. 편집기는 예제 형식에서 요청의 workspaceRoot로 워크스페이스를 지정하며, dir은 그 안에 머무르고 링크를 통해 밖으로 나가지 않는 상대 경로여야 합니다. HTTP를 통해서는 도구가 dir을 자신이 제공하는 워크스페이스로 제한하고, 표준 입력과 출력을 통해서는 다른 모든 경로와 마찬가지로 dir을 지정된 그대로 받습니다. 기능 인덱스는 그 형식 때문에 scaffold 도구를 쓰기 작업을 하는 것으로 보고하며, 이 명령을 별도 프로세스에서 실행하는 cli-scaffold도 쓰기 작업을 하는 것으로 보고합니다.
실행 가능한 예제에서 시작하기
문서에는 실행 가능한 예제가 포함되어 있습니다. 각 예제는 Aggregate, 그 Releases, 그리고 빌드에 쓰이는 그 밖의 모든 것을 담은 디렉터리이며, 빌드 방법을 설명하는 페이지가 함께 있습니다. --example은 그중 하나를 새 디렉터리에 쓰므로, 빈 프로젝트가 아니라 동작하는 프로젝트에서 시작할 수 있습니다:
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.무엇을, 어디에 쓰는가. 예제의 파일을 문서에 담긴 그대로 두 번째 인수로 지정한 디렉터리에 씁니다. 지정하지 않으면 명령을 실행한 폴더 안에 예제 이름을 딴 디렉터리에 씁니다. 디렉터리는 아직 존재하지 않거나 비어 있어야 합니다. 그 밖의 경우는 거부되며 원래 상태 그대로 남습니다. 즉 파일이 들어 있는 디렉터리, 그 경로에 있는 파일, 또는 링크입니다. 아직 존재하지 않는 상위 디렉터리는 생성됩니다. 예제의 파일은 다른 곳에 남지 않으며, 모든 파일이 쓰이기 전에는 어떤 파일도 제자리에 놓이지 않습니다. 파일은 먼저 별도의 위치에 쓰이고, 모두 준비되면 옮겨집니다.
다음에 출력하는 명령은 예제 자체 페이지가 제시하는 명령입니다. 페이지의 ## Build 제목 아래에 있는 첫 번째 sh, bash 또는 shell 블록을 페이지에 쓰인 그대로 주석까지 포함하여, 디렉터리로 이동하는 cd 다음에 출력합니다. 페이지에 그런 블록이 없는 예제는 대신 그 페이지의 경로로 응답합니다.
어떤 예제가 있는가. --list는 모든 예제를 문서가 가르치는 순서대로 한 번씩 출력하며(이름, 페이지가 선언하는 수준, 페이지의 첫 문장), 아무것도 쓰지 않습니다:
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....이 목록은 문서 자체의 예제 목록으로, 예제와 함께 제품 및 기능별 예제로 게시된 것입니다. 번들에 해당 예제가 없는 이름은 --list를 안내하며 거부되고, 아무것도 쓰이지 않습니다.
예제의 출처. 예제는 문서 번들에서 읽습니다. 문서 번들은 게시된 문서의 서명된 아카이브로, aggrega explain이 해설을 읽어 오는 곳이며, 워크스페이스의 기본 레지스트리에 게시되어 있습니다. 읽는 번들은 실행 중인 aggrega 버전용으로 게시된 번들입니다. 그 버전용으로 게시된 번들이 없으면 이전 릴리스용으로 게시된 가장 최신 번들을 읽으며, 명령은 표준 오류에 그 사실을 알립니다:
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릴리스 이후의 몇몇 커밋으로 빌드한 aggrega(aggrega version이 0.9.0-12-g1a2b3c4d처럼 표시되는 빌드)는 빌드의 기준이 된 릴리스(여기서는 0.9.0)의 문서를 읽고, 그것이 게시되지 않았으면 그 이전 릴리스의 문서를 읽습니다. 릴리스 후보 같은 사전 릴리스 이후의 몇몇 커밋으로 빌드한 것(aggrega version이 0.9.0-rc.6-4-gc9db2f597처럼 표시되는 빌드)은 그 사전 릴리스(여기서는 0.9.0-rc.6)의 문서를 읽고, 그것이 게시되지 않았으면 그 이전에 게시된 가장 최신 문서를 읽으며, 이전 사전 릴리스도 여기에 포함됩니다. 그 밖의 빌드는 자신이 바로 그 사전 릴리스일 때만 사전 릴리스의 문서를 읽습니다. 릴리스 번호 없이 찍힌 빌드는 자신의 버전의 문서를 읽거나 아무것도 읽지 않습니다. aggrega explain도 단계별 안내를 읽어 오는 번들을 같은 방식으로 선택합니다.
사용 중인 버전용으로 게시된 것이 없고 이전 것 중 최신 것이 이 버전의 aggrega가 더 이상 읽지 않는 형식인 경우 — 예를 들어 자체 문서가 게시되기 전에 실행한 릴리스 후보 — 명령은 두 가지를 한 문장으로 알리며 거부하고 아무것도 기록하지 않습니다:
[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사용하기 전에 검증합니다. 번들은 다른 모든 레지스트리 읽기와 같은 네트워크 설정으로 가져오며, 보관하기 전에 해당 레지스트리에 대한 워크스페이스의 서명 정책으로 서명을 확인합니다. 머신에 이미 있는 사본을 읽기 전에도 다시 확인하므로, 다른 프로젝트의 더 느슨한 정책이 들여온 사본이 이 워크스페이스의 정책 아래에서 사용되지 않습니다. 정책이 받아들이지 않는 번들은 거부되며 아무것도 쓰이지 않습니다.
머신당 한 번만 가져옵니다. 번들은 머신의 모든 Aggrega 프로젝트가 공유하는 캐시에 보관되므로(aggrega cache 참조), 두 번째 예제나 두 번째 프로젝트는 다시 다운로드할 필요가 없으며, 둘이 같은 버전을 읽는 경우 aggrega explain도 같은 사본을 읽습니다.
오프라인에서는 캐시된 것만 읽습니다. 오프라인 워크스페이스에서는 아무것도 가져오지 않습니다. 예제는 머신에 이미 있고 정책이 허용하는 사본(이 버전용 사본, 없으면 캐시된 이전 버전 중 가장 최신 사본)에서 쓰이며, 그런 사본이 없으면 명령은 모든 네트워크 읽기가 내는 오프라인 거부로 거부하고 네트워크를 허용하는 방법을 알려 줍니다.
예상치 못한 것을 담은 번들은 통째로 거부됩니다. 번들은 레지스트리에서 오므로, 추출 과정은 번들의 구조에 대해 아무것도 신뢰하지 않습니다. 이름이 지정한 디렉터리 밖이나 번들 밖에 놓이게 되는 항목, 그리고 링크이거나 파일 또는 디렉터리가 아닌 그 밖의 항목은 각각 그 항목을 명시하며 예제 전체를 거부하고, 아무것도 쓰이지 않습니다. 예제의 실행 파일은 실행 가능한 상태를 유지합니다.
워크스페이스의 구성을 읽습니다. 기본 레지스트리와 서명 정책은 구성에서 오므로, 워크스페이스 밖으로 이어지는 링크인 구성 파일은 구성을 읽는 다른 모든 명령을 멈추게 하는 것과 마찬가지로 예제 형식도 멈추게 합니다. 워크스페이스 경계를 참조하십시오.
예시
이름 없는 Release 초안을 작성하고 터미널에서 읽습니다:
aggrega scaffold releaseRecipe 초안을 바로 파일로 작성합니다:
aggrega scaffold recipe postgres-helm > postgres-helm.yaml무엇이든 채우기 전에 아직 채워야 할 값을 확인합니다:
aggrega scaffold component my-service > my-service.yamlaggrega validate my-service.yaml어떤 실행 가능한 예제가 있는지 확인한 다음, 그중 하나를 원하는 디렉터리에 씁니다:
aggrega scaffold --example --listaggrega scaffold --example redis-cache my-cache이 명령으로 시작하는 작성 루프(형태 초안 작성, 자리 표시자 채우기, 검증)는 Aggrega 파일 작성을 참고하십시오.