공식 CLI 개발 흐름

@morit/cli는 로컬 source 작성, Cloud Project 연결, signed build와 Deployment를 제공합니다.

설치 없이 실행

npx -y @morit/cli --help

Node.js 20.12 이상을 사용합니다. 자동화에서는 각 명령에 --json을 추가해 구조화된 출력을 받을 수 있습니다.

1. Setup

npx -y @morit/cli plugin setup . \
  --id com.example.study \
  --name "Study" \
  --publisher example

기존 유효 프로젝트에서는 ID 옵션 없이 실행할 수 있습니다. morit-plugin.json은 Project ID, organization ID, revision, source digest, API URL만 저장합니다.

2. Validate와 build

npx -y @morit/cli plugin validate .
npx -y @morit/cli plugin build . --output ./dist/study-1.0.0.mplg

build는 fragment를 compiled manifest로 합치고 source·asset·dependency 참조를 확인한 뒤 publisher별 Ed25519 key로 자동 서명합니다. source나 .mplg에는 private key를 넣지 않으며, build 결과를 같은 과정에서 다시 열어 signature와 package 구조를 확인합니다.

key는 publisher마다 하나이며 기본 위치는 ~/.morit/plugin-mcp/keys입니다. 공식 CLI와 Local MCP가 같은 key를 사용하고, 이전 Local MCP가 ~/.morit/plugin/keys에 만든 key는 처음 build할 때 자동으로 옮깁니다. 두 위치의 key가 서로 다르면 기본 위치의 key를 쓰고 경고를 출력합니다. 조직 key를 쓰려면 --key-dir <directory> 또는 MORIT_PLUGIN_KEY_DIR로 위치를 지정합니다. 같은 플러그인의 업데이트는 같은 key로 서명해야 하므로 이 디렉터리를 안전하게 백업하세요. build 결과의 public_key_sha256으로 어느 key를 썼는지 확인할 수 있습니다.

npx -y @morit/cli plugin preview . --output ./dist/preview.html

CLI와 Local/Remote MCP의 morit_project_preview는 같은 검증 계약을 먼저 통과시킵니다. Runtime v2 preview는 스크립트 없는 HTML이며 light/dark 토글을 포함합니다. Runtime v3 preview는 Morit Script를 실행하기 위해 SDK 인터프리터를 HTML에 포함하고 시스템 색상 모드를 따릅니다. 실제 Flutter route·focus·Tool 실행은 서명 package를 앱에 설치해 확인합니다.

3. 로그인

npx -y @morit/cli login

CLI가 브라우저 device flow를 열고 사용자가 표시된 코드를 승인합니다. Windows는 DPAPI, macOS는 Keychain, Linux는 Secret Service의 secret-tool을 사용합니다. CI는 세션 환경변수 MORIT_ACCESS_TOKEN을 사용할 수 있지만 source, 로그, artifact에 기록하지 않습니다.

npx -y @morit/cli logout

4. Cloud Project 연결

npx -y @morit/cli plugin add .

현재 조직에 Project를 만들고 local source를 연결합니다. 이미 연결된 프로젝트에서 다시 add하지 않습니다.

5. Sync

로컬 → Cloud:

npx -y @morit/cli plugin sync .

Cloud → 로컬:

npx -y @morit/cli plugin sync . --pull

마지막 sync 이후 로컬 변경이 있으면 pull이 중단됩니다. Cloud 사본으로 덮어쓸 의도가 명확할 때만 --pull --force를 사용합니다. revision 충돌은 새 파일을 읽고 변경을 합친 뒤 다시 push합니다.

6. Deploy

npx -y @morit/cli plugin deploy . --visibility private

명령은 최신 source push → local signed build → exact artifact upload → immutable Deployment 생성을 수행합니다. 응답의 deployment_id, local_artifact_path, SHA-256, visibility를 기록합니다. 처음에는 private로 실사용 테스트한 뒤 Marketplace metadata와 공개 준비가 끝났을 때 public으로 변경합니다.

npx -y @morit/cli deployment publish <deployment-id> --visibility public

Cloud와 로컬에서 같은 이름의 package를 다시 만들지 말고 Deployment가 가진 exact artifact hash를 설치 경로 전체에서 유지합니다.

조회와 삭제

npx -y @morit/cli project list
npx -y @morit/cli project get <project-id>
npx -y @morit/cli deployment list <project-id>
npx -y @morit/cli deployment get <deployment-id>
npx -y @morit/cli project delete <project-id>

활성 Deployment가 있는 Project 삭제는 서버 정책에 따라 거부될 수 있습니다. 사용자 설치를 Deployment 정리로 우회 삭제하지 않습니다.

CI 예

npx -y @morit/cli plugin validate . --json
npx -y @morit/cli plugin build . --output ./dist/plugin.mplg --json

배포 CI에는 최소 scope의 짧은 수명 token을 주입하고 작업이 끝나면 폐기합니다. build artifact의 SHA-256과 Deployment의 SHA-256을 비교합니다.