aggrega edit-document
건드리지 않는 모든 바이트를 보존하면서 문서에 범위가 제한된 구조적 편집 하나를 적용
개요
aggrega edit-document <edit> <file> [flags]설명
Apply one bounded structured edit to a document in the workspace.
The edit is named first and the document second. One call adds one entry under one container, or sets one scalar, and it can do nothing else:
add-component add a component instance under a components container attach-feature attach a Feature to the node you name wire-edge wire a connection inside one of that node's sockets set-value set one value on that node
There is no edit that deletes, replaces a block you already wrote, reorders anything, or writes bytes you supply verbatim. The edits this command applies are add-component, attach-feature, wire-edge, set-value, and a name outside that set is refused rather than interpreted.
Name the node with --node, once per path segment, from the document root. It is a segment at a time rather than one dotted string because a dot is a legal character in a name you type, so a joined path could address a key nobody wrote and the entry would be created there rather than refused:
aggrega edit-document add-component app.yaml \ --node spec --node components --name web --value example/service
aggrega edit-document wire-edge app.yaml \ --node spec --node components --node web \ --socket database --name db --value spec.components.store
For add-component the path names the components container itself, because the entry being added is the node. For the other three it names the node the edit is about, and the container follows from the edit.
--name is the key the entry is written under: the instance name, the attachment's name, the connection's alias, or the value's key. --value is what that entry carries, and what it means follows from the edit — the entity the entry requests, the node a connection points at, or the scalar a value is set to. It is read as a YAML scalar, so --value 3 sets a number, --value true a boolean, and --value '"3"' the string; omitting it sets nothing at all.
Every byte the edit does not touch survives. The document is parsed only to locate the container and the line its block ends at, so comments, blank lines, quoting style, folded and literal scalars and the trailing-newline shape all carry through, and the nesting step is measured from the document's own indentation rather than imposed. The same request against the same document produces the same bytes.
The result has to be a document you could have typed, and that is what the write is gated on: the composed document is checked against its own kind's schema and reaches disk only if that passes. A request that would produce something the schema refuses is refused, naming the property the schema would not admit and where, and the file is left byte-for-byte as it was — so a refused edit is indistinguishable from one never attempted and you can retry a corrected request against the document you started with.
An entry that is already there, carrying what you asked for, is a no-op. An entry of that name carrying something else is refused rather than replaced.
--dry-run does everything the plain command does except write: the edited document goes to standard output as content, naming the file it is for, and nothing is created — for a caller that puts the result in front of someone before it is saved. Every other behaviour is the write's, the schema gate included, so a request the write would refuse is refused under --dry-run too and its exit code predicts the write's. Without it the document is written.
Whether what you wire is semantically admissible is not decided here. Whether a socket is one the producer declares, or whether a Feature's applicability is satisfied, is what aggrega validate answers.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--dry-run | false | 쓰기를 제외한 모든 작업을 수행합니다. 편집된 문서를 대상 파일 이름과 함께 내용으로 반환하며, 아무것도 생성하거나 수정하지 않습니다. 스키마 검사를 포함한 그 밖의 모든 동작은 쓰기와 같습니다. 이 플래그가 없으면 문서가 기록됩니다 |
--name | — | 새 항목이 기록되는 키입니다. 컴포넌트 인스턴스 이름, 첨부의 이름, 연결의 별칭 또는 값의 키입니다 |
--node | [] | 편집 대상 노드까지 문서 루트에서 시작하는 구조 경로의 세그먼트 하나입니다. 세그먼트마다 한 번씩, 가장 바깥쪽부터 반복해서 지정합니다. 점으로 연결된 경로 하나가 아니라 세그먼트를 하나씩 받는 이유는 점이 직접 입력하는 이름에 쓸 수 있는 문자이므로, 연결된 경로가 아무도 작성하지 않은 키를 가리킬 수 있기 때문입니다 |
--socket | — | 연결이 배선되는 의존성 소켓입니다. wire-edge에서 읽히며 그 밖의 경우에는 무시됩니다 |
--value | — | 항목이 담는 내용으로, YAML 스칼라로 읽힙니다. 그 의미는 편집에 따라 정해집니다. 항목이 요청하는 엔터티, 연결이 가리키는 노드, 또는 값에 설정되는 스칼라입니다 |
동작
aggrega edit-document <edit> <file>은 워크스페이스에 있는 문서에 구조적 편집 하나를 적용하고, 건드리지 않은 모든 바이트는 작성한 그대로 둡니다. 편집을 먼저 지정하고 문서를 그다음에 지정합니다:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components \ --name checkout --value core/api-server:1.0.0이 명령은 어디를 편집할지 안내받기보다 파일이 직접 편집되기를 원하는 경우를 위해 존재합니다. 자체 버퍼와 자체 실행 취소 기록을 유지한다면, aggrega serve가 위치를 알려 주고 텍스트는 직접 배치하게 합니다. 이 명령은 항목을 구성하여 기록합니다.
문서는 워크스페이스가 포함하는 문서여야 합니다. 워크스페이스 루트에 대한 상대 경로나 절대 경로로 지정합니다. 워크스페이스 밖의 문서는 아무것도 읽거나 쓰지 않은 채 거부되며, 이는 경로가 그렇게 작성된 경우든 워크스페이스 밖으로 이어지는 링크를 통해 도달한 경우든 마찬가지입니다. 여기서 링크란 파일에 대한 링크이거나, 경로 도중에 있는 링크인 디렉터리입니다. 편집은 문서를 다시 쓰기 전에 먼저 읽으므로, 그러한 링크 너머의 문서는 워크스페이스가 포함하지 않는 파일이며, 거부 메시지가 이를 알려 줍니다:
the document named leads outside the workspace through a link, and an edit is only applied to a document the workspace carries: "shared/storefront.aggregate.yaml"다른 곳에 있는 문서를 편집하려면 해당 문서를 포함하는 워크스페이스에서 명령을 실행합니다. 언어 서버의 편집과 어시스턴트 도구의 편집도 같은 규칙을 적용하는데, 셋 모두 하나의 편집을 적용하기 때문입니다. 워크스페이스 경계에서 설명하듯이, 그 문서는 입력하는 경로 가운데 워크스페이스 안으로 제한되는 유일한 경로입니다.
한 번의 호출에 항목 하나, 그리고 집합은 닫혀 있습니다
편집은 네 가지이며 그 외에는 없습니다:
| 편집 | 추가하는 것 |
|---|---|
add-component | components 컨테이너 아래의 컴포넌트 인스턴스 |
attach-feature | 지정한 노드에 대한 Feature 연결 |
wire-edge | 해당 노드의 의존성 소켓 중 하나 안의 연결 |
set-value | 지정한 노드의 값 하나 |
삭제하거나, 이미 작성한 블록을 교체하거나, 무언가의 순서를 바꾸거나, 제공한 바이트를 그대로 쓰는 편집은 없습니다. 이는 설계에 대한 제약이 아니라 설계 그 자체입니다. 네 가지 외의 이름은 이 명령을 통과할 경로가 전혀 없으므로, 이 명령은 더 좁은 이름을 단 파일 작성기가 아닙니다. 집합 밖의 이름은 해석되지 않고 거부됩니다.
요청한 내용을 담은 항목이 이미 있으면 아무 작업도 하지 않습니다 — 명령은 그렇다고 알리고 아무것도 쓰지 않습니다:
storefront.aggregate.yaml already carries that entry; nothing was written같은 이름의 항목이 다른 내용을 담고 있으면 교체되지 않고 거부됩니다. 작성한 내용을 교체하는 것은 네 가지 편집에 속하지 않기 때문입니다.
노드는 경로로, 한 번에 한 세그먼트씩 지정합니다
--node는 문서 루트에서 시작하는 경로의 세그먼트마다 한 번씩, 가장 바깥쪽부터 반복해서 지정합니다:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket database --name replica --value store점으로 구분한 하나의 경로 대신 한 번에 한 세그먼트씩 받는 것은 의도된 것이며, 그 이유는 정확성에 있습니다. 점은 입력하는 이름에 쓸 수 있는 문자이므로, 문서 바깥에서는 구조를 나타내는 점과 이름 안의 점을 구별할 수 없습니다. 이어 붙인 경로는 올바르게 읽히면서도 아무도 작성하지 않은 키를 가리킬 수 있습니다. 그리고 add-component는 문서에 없는 컨테이너를 만들 수 있으므로, 항목은 거부되지 않고 그렇게 만들어진 키 아래에 추가됩니다. 세그먼트는 모호함을 다른 곳으로 옮기는 것이 아니라 없앱니다.
add-component의 경우 경로는 components 컨테이너 자체를 가리킵니다. 추가되는 항목이 바로 그 노드이기 때문입니다. 나머지 세 가지의 경우 경로는 편집 대상 노드를 가리키며, 컨테이너는 편집에 따라 정해집니다. attachment는 그 노드의 features 아래에, connection은 그 노드의 uses와 지정한 소켓 아래에, 값은 그 노드의 values 아래에 들어갑니다.
--name은 항목이 기록되는 키입니다. 즉 인스턴스 이름, attachment의 이름, connection의 별칭 또는 값의 키입니다. --socket은 wire-edge에서만 읽히고 그 밖의 경우에는 무시됩니다.
값은 그 문자가 나타내는 타입을 유지합니다
--value는 YAML 스칼라로 읽히며, 이는 같은 문자를 문서에 직접 입력했을 때 읽히는 방식과 같습니다.
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node components --node web --name workers --value 4 values: replicas: 3 workers: 4따라서 --value 4는 숫자를, --value true는 불리언을, --value '"4"'는 문자열 4를 설정합니다. 여기서 따옴표는 문서에서와 똑같이 “이것은 텍스트다”라는 뜻입니다. --value를 생략하면 아무것도 설정하지 않습니다. 매핑이나 시퀀스는 거부됩니다. 이를 쓰는 것은 블록을 추가하는 일이며, 이는 네 가지 편집 중 하나가 아니기 때문입니다.
편집하지 않은 모든 것은 유지되며, 같은 요청은 같은 바이트를 생성합니다
문서는 컨테이너와 그 블록이 끝나는 줄을 찾기 위해서만 파싱되며, 항목은 렌더링된 뒤 줄 단위로 삽입됩니다. 주석, 빈 줄, 인용 스타일, 접힌 스칼라와 리터럴 스칼라, 템플릿 표현식, 끝 줄바꿈의 형태는 모두 변경 없이 그대로 유지되며, 중첩 단계는 강제로 적용되지 않고 문서 자체의 들여쓰기에서 측정됩니다. 따라서 항목은 이미 작성하고 있는 스타일대로 들어갑니다.
같은 문서와 같은 요청이 주어지면 바이트는 매번 같습니다. 따라서 두 번의 실행을 비교할 수 있으며, 리뷰에서는 하나의 편집을 하나의 diff로 읽게 됩니다.
결과는 직접 입력할 수도 있었던 문서여야 합니다
쓰기는 바로 이 조건을 통과해야만 이루어집니다. 구성된 문서는 해당 문서 kind의 스키마에 대해 검사되며, 이 스키마는 사용자가 제공하는 것이 아니라 문서에서 읽어 옵니다. 검사를 통과한 경우에만 바이트가 디스크에 기록됩니다. 스키마가 거부할 결과를 만들어 낼 요청은 거부되며, 스키마가 허용하지 않을 속성과 그 위치가 함께 표시됩니다:
the edit was refused because the resulting document would not be valid, and nothingwas written: document envelope validation failed (Release, at prod.release.yaml);15:7: spec.components.web.values: … unexpected property: "values"파일은 바이트 단위까지 원래 상태 그대로 남으며, 쓰기 자체도 원자적입니다. 따라서 거부되거나 중단된 편집은 시도한 적이 없는 편집과 구별되지 않으며, 처음 시작한 문서에 대해 수정한 요청을 다시 시도할 수 있습니다. 여기서 작성 규칙을 다시 설명하지 않는 이유도 이 때문입니다. Release 문서에 개발자 값을 넣으라는 요청은 손으로 입력한 문서를 거부할 바로 그 스키마에 의해 거부됩니다.
무엇이 의미상 허용되는지는 여기서 결정되지 않습니다. 의존성 소켓이 생산자가 선언한 것인지, 또는 Feature의 적용 조건이 충족되는지는 빌드가 수행하는 해석 단계에서 판단합니다. 따라서 이 명령이 전혀 모르는 연결을 지정할 수 있으며, Aggregate는 해당 카탈로그 엔터티가 미리 선언하지 않은 소켓을 작성할 수 있습니다. 소켓을 통해 무엇을 소비할 수 있는지는 여전히 생산자가 선언합니다. 이 점이 궁금하다면 Release를 지정하여 aggrega validate를 실행하십시오.
저장하기 전에 결과 확인하기
--dry-run은 쓰기를 제외하고 일반 명령이 하는 모든 작업을 수행합니다. 편집된 문서는 대상 파일의 이름과 함께 콘텐츠로서 표준 출력으로 전달되며, 아무것도 생성되지 않습니다:
aggrega edit-document attach-feature storefront.aggregate.yaml \ --node spec --node components --node web \ --name tls --value core/tls:1.0.0 --dry-rundocuments: - path: storefront.aggregate.yaml content: | # The storefront application. ...이 플래그가 없으면 문서가 기록됩니다. 기본 동작은 쓰기입니다. 이 명령의 산출물은 편집된 문서이며, 문서를 만들어 내는 명령은 그 문서를 전달할 책임이 있기 때문입니다. 전달 방식에 대해 아무것도 지정하지 않은 요청은 파일을 편집합니다.
그 밖의 모든 동작은 쓰기와 동일하며, 검증 게이트도 마찬가지입니다. 결과를 스키마가 거부할 편집은 --dry-run에서도 거부되며, 같은 속성을 지목하고 파일을 원래 상태 그대로 둡니다. 따라서 dry run에서 받는 종료 코드는 쓰기를 했을 때 받았을 종료 코드와 같습니다.
편집기나 어시스턴트에서 수행하는 동일한 편집
어떤 경로로 편집을 적용하든 바이트는 동일합니다. aggrega serve를 구동하는 편집기는 aggrega/editDocument를 통해 이 기능에 접근하고, aggrega mcp로 연결된 AI 어시스턴트는 이 명령이 그곳에서 노출되는 도구로 접근합니다. 항목의 구성, 삽입, 검증 게이트는 한곳에서 이루어지며 각 경로는 그 위에 얹힌 얇은 진입점일 뿐입니다. 따라서 터미널에서 편집한 문서와 편집기가 대신 편집한 문서는 바이트 단위로 동일합니다.
경로 간에 유일하게 다른 점은 어떤 바이트를 읽느냐입니다. 이 명령과 세션 메서드는 모두 디스크에 있는 파일을 읽으며, 저장되지 않은 버퍼는 절대 읽지 않습니다. 버퍼에서 쓰면 항목 하나를 적용한다는 명목으로 저장하지 않은 내용까지 페이지에 기록하게 되기 때문입니다. 먼저 저장한 다음 편집하십시오.
예시
Aggregate의 최상위 수준에 component 인스턴스를 추가합니다:
aggrega edit-document add-component storefront.aggregate.yaml \ --node spec --node components --name checkout --value core/api-server:1.0.0서브시스템 안에 작성된 component에 Feature를 연결합니다:
aggrega edit-document attach-feature storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name audit-log --value core/observability/audit-log:1.0.0서브시스템 안에서 작성된 컴포넌트에 값을 설정합니다:
aggrega edit-document set-value storefront.aggregate.yaml \ --node spec --node subsystems --node billing --node components --node ledger \ --name replicas --value 5아무것도 기록되기 전에 결과를 검토합니다:
aggrega edit-document wire-edge storefront.aggregate.yaml \ --node spec --node components --node web \ --socket cache --name sessions --value redis --dry-run컨테이너를 지정하기 전에 항목이 어느 컨테이너에 속하는지 알아보려면, 그리고 아무것도 적용하지 않고 위치를 읽으려면 aggrega serve를 참조하십시오.