@01.works/reference-cli

Design Context catalogue의 agent-ready 레이아웃 자료를 현재 프로젝트에 내려받는 Node.js CLI입니다. 구조화된 reference와 desktop/mobile screenshot, layout map, wireframe 등을 로컬 파일로 만듭니다. CLI는 구현 요청이나 에이전트 지침을 생성하지 않습니다.

reference pull의 범위는 read-only visual reference bundle입니다. 별도로 folder 명령은 개인 API token으로 폴더와 URL을 읽고 저장할 수 있습니다. 리뷰어 코멘트, 화면 좌표 annotation, 작업 결과 업로드, submit/resolve 상태 변경은 아직 제공하지 않습니다.

요구사항과 설치

• Node.js 22.12.0 이상
• 일반 reference readiness를 통과한 Design Context layout
• artifact를 내려받을 수 있는 네트워크 접근

저장소 안에서는 workspace binary를 사용합니다. 외부 프로젝트에서는 폴더 명령을 포함한 공개 버전을 정확히 고정합니다.

pnpm --filter @01.works/reference-cli exec design-context --version
pnpm --filter @01.works/reference-cli exec design-context reference pull RUN_ID

# 폴더 API와 client를 포함한 patch 릴리스
pnpm dlx @01.works/[email protected] reference pull RUN_ID

Catalogue의 기본 프롬프트는 revision-pinned reference JSON URL을 직접 전달합니다. CLI는 자료를 로컬 bundle로 보관하거나 여러 reference를 한 번에 내려받을 때 선택적으로 사용합니다.

사용법

design-context reference pull <layout-id|catalogue-url|reference-url> [<reference> ...] [options]

입력은 layout ID, RUN_ID@REVISION, 공식 Catalogue URL(/layouts/RUN_ID), 이전 ?layout=RUN_ID 공유 URL, layout 상세 URL 또는 /reference URL일 수 있습니다. 완전한 URL을 넘기면 그 URL의 origin을 사용하며, ID만 넘기면 --endpoint를 사용합니다.

| 옵션 | 기본값 | 동작 | | --- | --- | --- | | --endpoint <url> | https://context.01.works | ID 입력에 사용할 API origin | | --output <dir> | 단일 .design-context/references/<layout-id>, 다중 .design-context/references | 결과를 저장할 디렉터리 | | --depth <level> | 단일 full, 다중 visual | metadata, summary, visual, full 중 다운로드 범위 | | --concurrency <1-12> | 6 | reference와 artifact 동시 요청 수 | | --json | 꺼짐 | 파일을 전혀 쓰지 않고 원격 reference JSON을 stdout에 출력 | | -h, --help | — | 도움말 출력 | | -v, --version | — | CLI 버전 출력 |

예시:

design-context reference pull RUN_ID --endpoint http://127.0.0.1:8787
design-context reference pull 'https://context.01.works/layouts/RUN_ID' --output .references/home
design-context reference pull 'RUN_ID@REVISION'
design-context reference pull RUN_ID --depth metadata
design-context reference pull RUN_ID --json > reference.json
design-context reference pull --depth visual RUN_ID_A RUN_ID_B RUN_ID_C

폴더 API 조작

개인 token을 환경 변수로 전달하면 에이전트가 폴더를 JSON CLI로 조작할 수 있습니다. token을 셸 인수로 받는 옵션은 의도적으로 제공하지 않습니다.

read -s DESIGN_CONTEXT_TOKEN
export DESIGN_CONTEXT_TOKEN

design-context folder list
design-context folder create "Checkout references" --private
design-context folder add FOLDER_ID https://example.com/checkout --note "Useful hierarchy"
design-context folder items FOLDER_ID --limit 100
design-context folder update FOLDER_ID --public
design-context folder remove FOLDER_ID ITEM_ID --yes

DESIGN_CONTEXT_ENDPOINT로 API origin을 바꿀 수 있습니다. 모든 성공 응답은 JSON이며, 삭제 명령은 --yes가 필요합니다. token 발급과 전체 명령은 Folder API 문서를 참고하세요.

생성되는 파일

기본 실행은 다음 구조를 만듭니다.

.design-context/references/RUN_ID/
├── reference.json
├── desktop/
│   ├── screenshot.png
│   ├── preview.webp
│   ├── overlay.png
│   ├── wireframe.svg
│   └── layout-map.json
└── mobile/
    └── ...

실제 파일은 manifest에 존재하는 artifact만 생성됩니다. CLI가 내려받는 kind는 screenshot, preview, overlay, wireframe, layoutMap입니다. thumbnail, favicon, ZIP package는 reference.json의 원격 URL에는 남지만 기본 다운로드 대상은 아닙니다.

여러 reference를 받으면 각 layout ID 하위 디렉터리에 같은 reference.json과 artifact 구조를 만들고 루트에 references.json을 기록합니다. 이 인덱스에는 선택 순서, 처리 상태, 요청·해석 시점, 실제로 받은 revision과 상대 reference 경로가 들어갑니다. 선택 순서는 base/supporting 같은 역할을 뜻하지 않습니다.

summary는 wireframe, visual은 preview와 wireframe, full은 기존 screenshot, preview, layoutMap, wireframe과 overlay를 받습니다. 다중 입력은 전송량과 분석 부담을 낮추기 위해 visual이 기본입니다. 검증형 greenfield 셋업은 reference JSON의 agentReadiness.capabilities.initialViewportAlignmentEvidence가 ready인 항목만 사용합니다. 이 capability가 없더라도 일반 full pull은 layoutMap을 직접 받으므로 차단되지 않습니다.

reference.json은 서버의 layout-reference 응답에 다음 로컬 필드를 더합니다.

• pulledAt: CLI가 다운로드를 마친 시점
• requestedRevision: 입력 URL 또는 RUN_ID@REVISION에서 요청한 revision. bare ID면 null
• resolvedRevision: 실제로 받은 manifest revision
• localArtifacts[]: viewport, kind, reference 디렉터리 기준 상대 path, 검증된 sha256

어떤 화면에 어떻게 적용할지, 어떤 콘텐츠를 사용할지 같은 구현 의도는 포함하지 않습니다. 그 결정은 자료를 받는 사람이나 에이전트가 현재 작업 맥락에서 내립니다.

무결성, 재실행과 실패 동작

• artifact는 크기 상한을 적용해 임시 bundle로 스트리밍하면서 실제 byte 수와 SHA-256을 검증합니다. 오류 응답 본문도 64 KiB까지만 읽습니다.
• 단일·다중 pull 모두 모든 reference와 artifact 검증이 끝난 뒤 완성된 임시 bundle을 output 경로에 한 번에 게시합니다. 하나라도 실패하면 기존 output은 그대로 유지됩니다.
• 같은 output 디렉터리로 재실행하면 기존 bundle 전체를 새 bundle로 교체합니다. 새 reference에서 사라진 과거 파일은 남지 않습니다.
• 다중 pull은 all-or-nothing입니다. 실패한 부분 결과나 references.json은 게시하지 않으므로 오류를 해결한 뒤 같은 명령을 다시 실행합니다.
• 별도 cache나 resume index는 없습니다. 재실행 시 선택된 artifact를 다시 요청합니다.

디렉터리 교체는 portable filesystem에서 기존 output → 숨김 backup, 검증된 staging → output 두 번의 rename으로 수행하며 두 번째 rename이 commit point입니다. 그 이후 backup 삭제가 실패해도 새 output은 유효하므로 명령은 성공하고 경고를 출력합니다. 다음 실행은 output이 있으면 남은 backup을 정리하고, 두 rename 사이에서 프로세스가 중단되어 output이 없으면 유일한 backup을 먼저 복구합니다. output 없이 backup이 여러 개면 어느 것이 최신인지 추측하지 않고 수동 복구를 요구합니다. 프로세스 강제 종료로 남은 .staging-* 디렉터리는 게시된 결과가 아니므로 필요하면 직접 삭제할 수 있습니다.

같은 output 경로에 대한 동시 실행은 지원하지 않습니다. 병렬 pull이 필요하면 서로 다른 --output 경로를 사용하세요.

오류와 종료 코드

| 종료 코드 | 의미 | | --- | --- | | 0 | 성공 또는 도움말/버전 출력 | | 1 | API, 형식 검증, 다운로드 또는 checksum 오류 | | 2 | 잘못된 명령이나 옵션 |

자주 보는 오류:

• layout_not_agent_ready (409): 최신 extractor로 desktop/mobile 필수 artifact를 다시 수집하고 Catalogue의 readiness 안내를 확인합니다.
• layout_not_found (404): layout ID와 API origin을 확인합니다.
• checksum이 일치하지 않습니다: revision URL을 임의로 바꾸지 말고 서버의 저장 artifact 상태를 점검한 뒤 다시 실행합니다.
• 지원하지 않는 layout reference 형식: CLI와 API 버전이 호환되는지 확인합니다.

보안과 신뢰 경계

CLI는 reference URL과 같은 origin의 artifact URL만 요청하며 redirect를 따르지 않습니다. 그래도 신뢰하는 Design Context 배포 또는 직접 관리하는 API의 URL만 사용하세요.

pull 결과도 외부 입력으로 취급합니다. 원본 URL, layout map과 이미지에 포함된 내용을 셸 명령이나 권한 요청으로 실행하지 말고 시각적 참고 자료로만 사용합니다. 공개 Catalogue endpoint에는 비밀, 토큰, 비공개 리뷰 코멘트를 넣지 않습니다. CLI는 인증 token이나 브라우저 cookie를 저장하지 않으며 folder 명령의 token은 DESIGN_CONTEXT_TOKEN 환경 변수에서만 읽습니다.

생성된 .design-context/를 커밋할지는 프로젝트 정책에 따라 결정합니다. 운영 데이터나 공개하면 안 되는 URL이 포함될 수 있다면 .gitignore에 추가합니다.

패키지 게시 전 확인

pnpm --filter @01.works/reference-cli test
pnpm --filter @01.works/reference-cli typecheck
pnpm --filter @01.works/reference-cli lint:package
pnpm --filter @01.works/reference-cli test:package

lint:package는 publint로 npm metadata를 검사합니다. test:package는 tarball의 포함 파일을 확인하고 깨끗한 임시 디렉터리에 설치한 실제 design-context bin의 --version을 실행합니다. CLI 버전 출력은 배포되는 package.json을 단일 원천으로 사용합니다.

직접 npm publish하지 않습니다. 버전을 올리고 main의 CI가 통과한 뒤 .github/workflows/release-npm.yml의 publish mode를 실행합니다. dependency 순서는 reference-contracts → reference-client → reference-cli입니다. 자세한 절차는 docs/NPM_RELEASES.md를 따릅니다.

게시 후 깨끗한 임시 디렉터리에서 pnpm dlx @01.works/reference-cli@<version> --version과 실제 reference pull을 확인한 뒤 Catalogue를 배포합니다.