구축·운영

CLI (surface + harness)

opt-cli는 Surface 검색·미리보기·복사·점검·업데이트와 harness 계약 검증을 통합한 운영형 CLI입니다.

reopt design업데이트 2026년 6월 26일

1. 개요

opt-cli는 shadcn/ui식 source copy 모델을 따르되, 설치 전 조회와 운영 점검까지 포함합니다. Core/Shells는 @reopt-ai/opt-ui, 차트는 @reopt-ai/opt-charts 패키지로 import 하고, Surface만 프로젝트 로컬로 복사해서 직접 수정합니다.

현재 registry에는 38개 Surface가 포함됩니다.
CLI는 bundled registry.json 을 source of truth로 사용합니다.
binary는 opt이며, Surface 명령은 opt surface <cmd> 형태입니다. harness 계약 검증은 opt harness <cmd>로 별도 제공.

2. 사전 요구사항

Surface는 내부에서 opt-ui Core/Shells와 필요 시 opt-charts를 import 합니다. 프로젝트에는 @reopt-ai/opt-ui와 필요한 전문 패키지를 설치하고, 반복 실행할 CLI는 @reopt-ai/opt-cli를 dev dependency로 둘 수 있습니다.

bash

bun add @reopt-ai/opt-ui
bun add -D @reopt-ai/opt-cli

# 설치 상태 / 프로젝트 정보 확인
npx @reopt-ai/opt-cli surface info

# 통합 상태 점검
npx @reopt-ai/opt-cli surface doctor

3. 검색과 조회

설치 전에 목록, 검색, 상세 메타를 확인할 수 있습니다. list와 search는 같은 명령 surface를 공유합니다.

bash

# 전체 목록
npx @reopt-ai/opt-cli surface list

# slug / 설명 / tags 검색
npx @reopt-ai/opt-cli surface search --query billing

# source package 기준 필터
npx @reopt-ai/opt-cli surface list --source opt-ui-surface

# 설치된 것만 보기
npx @reopt-ai/opt-cli surface list --installed

# JSON 출력
npx @reopt-ai/opt-cli surface search --query dashboard --json

# 개별 Surface 메타 조회
npx @reopt-ai/opt-cli surface view billing-page
npx @reopt-ai/opt-cli surface view billing-page --json

4. add: 설치 전 preview와 실제 복사

add는 preview와 실제 write를 모두 담당합니다. preview 계열은 파일을 쓰지 않습니다.

bash

# 기본 설치
npx @reopt-ai/opt-cli surface add billing-page

# 여러 개 한 번에 설치
npx @reopt-ai/opt-cli surface add billing-page analytics-dashboard

# 생성될 파일 내용만 보기
npx @reopt-ai/opt-cli surface add billing-page --view
npx @reopt-ai/opt-cli surface add billing-page --view billing-page.tsx

# 현재 로컬 파일과 registry diff 보기
npx @reopt-ai/opt-cli surface add billing-page --diff

# 실제 write 없이 설치 계획만 보기
npx @reopt-ai/opt-cli surface add billing-page --dry-run

# overwrite prompt 없이 덮어쓰기
npx @reopt-ai/opt-cli surface add billing-page --overwrite

# registry가 요구하는 외부 패키지도 같이 설치
npx @reopt-ai/opt-cli surface add data-explorer --install

5. opt-ui.json v2

첫 설치 시 opt-ui.json이 생성됩니다. v2 스키마는 Surface별 파일 target과 installed hash를 같이 기록해서 update/doctor가 로컬 수정을 판별합니다.

json

{
  "$schema": "https://opt-ui.dev/opt-ui.schema.json",
  "schemaVersion": 2,
  "surfacesDir": "components/surfaces",
  "importAlias": "@/components/surfaces",
  "surfaces": [
    {
      "slug": "billing-page",
      "version": "1.0.7",
      "contentHash": "e33ec0c3",
      "installedAt": "2026-03-11",
      "files": [
        {
          "target": "billing-page.tsx",
          "installedContentHash": "e33ec0c3"
        }
      ]
    }
  ]
}

surfacesDir: Surface가 복사되는 루트 디렉토리
importAlias: docs와 CLI 예시에 쓰는 import prefix
surfaces[].files[]: 각 target 파일과 마지막 설치 시점의 content hash

6. info / doctor

설치 상태를 보기만 할 때는 info, 실제 이상 여부를 검사할 때는 doctor를 사용합니다.

bash

# package manager, framework, registry version, config 상태
npx @reopt-ai/opt-cli surface info
npx @reopt-ai/opt-cli surface info --json

# blocking issue + warning 검사
npx @reopt-ai/opt-cli surface doctor

# legacy opt-ui.json migration을 저장
npx @reopt-ai/opt-cli surface doctor --fix

doctor가 보는 핵심 항목

@reopt-ai/opt-ui dependency 존재 여부
opt-ui.json 파싱 가능 여부와 schema migration 상태
설치된 Surface 파일 누락 / 로컬 수정 여부
@reopt-ai/opt-ui/tailwind.css import 여부

7. update workflow

update는 마지막 설치 hash와 현재 로컬 파일이 같을 때만 자동으로 덮어씁니다. 로컬 수정이 있으면 기본적으로 중단하고 diff를 보도록 유도합니다.

bash

# 전체 installed Surface 업데이트
npx @reopt-ai/opt-cli surface update

# 특정 slug만 업데이트
npx @reopt-ai/opt-cli surface update billing-page

# 로컬 수정본까지 강제로 덮어쓰기
npx @reopt-ai/opt-cli surface update billing-page --force

# 단일 Surface diff 확인
npx @reopt-ai/opt-cli surface add billing-page --diff

# 설치된 Surface 전체 drift 확인
npx @reopt-ai/opt-cli surface diff
npx @reopt-ai/opt-cli surface diff --json --format summary
npx @reopt-ai/opt-cli surface diff --exit-code

8. harness 계약 검증

opt harness 명령은 opt-shell runtime이 따르는 authored contract를 검사합니다. 정적 분석은 check, 브라우저 fixture 검증은 test, 환경/버전 진단은 doctor로 분리되어 있습니다.

bash

# Tier 1: 정적 contract/lint 검사
npx @reopt-ai/opt-cli harness check
npx @reopt-ai/opt-cli harness check --json
npx @reopt-ai/opt-cli harness check --fix
npx @reopt-ai/opt-cli harness check --rule harness/workspace-first

# Tier 2: fixture 기반 런타임 검증
npx @reopt-ai/opt-cli harness test
npx @reopt-ai/opt-cli harness test --fixture ./harness.fixtures.ts

# 환경/버전/contract 진단
npx @reopt-ai/opt-cli harness doctor
npx @reopt-ai/opt-cli harness doctor --fix

9. 설치 후 구조

text

my-app/
├── components/
│   └── surfaces/
│       └── billing-page.tsx
├── opt-ui.json
└── package.json

구축·운영

CLI (surface + harness)

opt-cli는 Surface 검색·미리보기·복사·점검·업데이트와 harness 계약 검증을 통합한 운영형 CLI입니다.

reopt design업데이트 2026년 6월 26일

1. 개요

현재 registry에는 38개 Surface가 포함됩니다.
CLI는 bundled registry.json 을 source of truth로 사용합니다.
binary는 opt이며, Surface 명령은 opt surface <cmd> 형태입니다. harness 계약 검증은 opt harness <cmd>로 별도 제공.

2. 사전 요구사항

bash

bun add @reopt-ai/opt-ui
bun add -D @reopt-ai/opt-cli

# 설치 상태 / 프로젝트 정보 확인
npx @reopt-ai/opt-cli surface info

# 통합 상태 점검
npx @reopt-ai/opt-cli surface doctor

3. 검색과 조회

설치 전에 목록, 검색, 상세 메타를 확인할 수 있습니다. list와 search는 같은 명령 surface를 공유합니다.

bash

# 전체 목록
npx @reopt-ai/opt-cli surface list

# slug / 설명 / tags 검색
npx @reopt-ai/opt-cli surface search --query billing

# source package 기준 필터
npx @reopt-ai/opt-cli surface list --source opt-ui-surface

# 설치된 것만 보기
npx @reopt-ai/opt-cli surface list --installed

# JSON 출력
npx @reopt-ai/opt-cli surface search --query dashboard --json

# 개별 Surface 메타 조회
npx @reopt-ai/opt-cli surface view billing-page
npx @reopt-ai/opt-cli surface view billing-page --json

4. add: 설치 전 preview와 실제 복사

add는 preview와 실제 write를 모두 담당합니다. preview 계열은 파일을 쓰지 않습니다.

bash

# 기본 설치
npx @reopt-ai/opt-cli surface add billing-page

# 여러 개 한 번에 설치
npx @reopt-ai/opt-cli surface add billing-page analytics-dashboard

# 생성될 파일 내용만 보기
npx @reopt-ai/opt-cli surface add billing-page --view
npx @reopt-ai/opt-cli surface add billing-page --view billing-page.tsx

# 현재 로컬 파일과 registry diff 보기
npx @reopt-ai/opt-cli surface add billing-page --diff

# 실제 write 없이 설치 계획만 보기
npx @reopt-ai/opt-cli surface add billing-page --dry-run

# overwrite prompt 없이 덮어쓰기
npx @reopt-ai/opt-cli surface add billing-page --overwrite

# registry가 요구하는 외부 패키지도 같이 설치
npx @reopt-ai/opt-cli surface add data-explorer --install

5. opt-ui.json v2

첫 설치 시 opt-ui.json이 생성됩니다. v2 스키마는 Surface별 파일 target과 installed hash를 같이 기록해서 update/doctor가 로컬 수정을 판별합니다.

json

{
  "$schema": "https://opt-ui.dev/opt-ui.schema.json",
  "schemaVersion": 2,
  "surfacesDir": "components/surfaces",
  "importAlias": "@/components/surfaces",
  "surfaces": [
    {
      "slug": "billing-page",
      "version": "1.0.7",
      "contentHash": "e33ec0c3",
      "installedAt": "2026-03-11",
      "files": [
        {
          "target": "billing-page.tsx",
          "installedContentHash": "e33ec0c3"
        }
      ]
    }
  ]
}

surfacesDir: Surface가 복사되는 루트 디렉토리
importAlias: docs와 CLI 예시에 쓰는 import prefix
surfaces[].files[]: 각 target 파일과 마지막 설치 시점의 content hash

6. info / doctor

설치 상태를 보기만 할 때는 info, 실제 이상 여부를 검사할 때는 doctor를 사용합니다.

bash

# package manager, framework, registry version, config 상태
npx @reopt-ai/opt-cli surface info
npx @reopt-ai/opt-cli surface info --json

# blocking issue + warning 검사
npx @reopt-ai/opt-cli surface doctor

# legacy opt-ui.json migration을 저장
npx @reopt-ai/opt-cli surface doctor --fix

doctor가 보는 핵심 항목

@reopt-ai/opt-ui dependency 존재 여부
opt-ui.json 파싱 가능 여부와 schema migration 상태
설치된 Surface 파일 누락 / 로컬 수정 여부
@reopt-ai/opt-ui/tailwind.css import 여부

7. update workflow

update는 마지막 설치 hash와 현재 로컬 파일이 같을 때만 자동으로 덮어씁니다. 로컬 수정이 있으면 기본적으로 중단하고 diff를 보도록 유도합니다.

bash

# 전체 installed Surface 업데이트
npx @reopt-ai/opt-cli surface update

# 특정 slug만 업데이트
npx @reopt-ai/opt-cli surface update billing-page

# 로컬 수정본까지 강제로 덮어쓰기
npx @reopt-ai/opt-cli surface update billing-page --force

# 단일 Surface diff 확인
npx @reopt-ai/opt-cli surface add billing-page --diff

# 설치된 Surface 전체 drift 확인
npx @reopt-ai/opt-cli surface diff
npx @reopt-ai/opt-cli surface diff --json --format summary
npx @reopt-ai/opt-cli surface diff --exit-code

8. harness 계약 검증

bash

# Tier 1: 정적 contract/lint 검사
npx @reopt-ai/opt-cli harness check
npx @reopt-ai/opt-cli harness check --json
npx @reopt-ai/opt-cli harness check --fix
npx @reopt-ai/opt-cli harness check --rule harness/workspace-first

# Tier 2: fixture 기반 런타임 검증
npx @reopt-ai/opt-cli harness test
npx @reopt-ai/opt-cli harness test --fixture ./harness.fixtures.ts

# 환경/버전/contract 진단
npx @reopt-ai/opt-cli harness doctor
npx @reopt-ai/opt-cli harness doctor --fix

9. 설치 후 구조

text

my-app/
├── components/
│   └── surfaces/
│       └── billing-page.tsx
├── opt-ui.json
└── package.json