@morit/cli 1.3.0 → 1.4.2

package/assets/docs/ui-runtime-v2.md

@@ -1,343 +0,0 @@
-# UI Runtime v2 레퍼런스
-
-UI Runtime v2는 서명된 `.mplg`가 화면, 상태, data source, action을 JSON으로 선언하는 Host-rendered
-계약입니다. Flutter/Dart, JavaScript, HTML, CSS, WebView, native code를 UI로 실행하지 않습니다.
-
-## Config 구조
-
-```json
-{
-  "ui_schema": 2,
-  "icon": "calendar",
-  "description": "오늘과 이번 주 학교 생활을 확인합니다.",
-  "theme": {
-    "density": "standard",
-    "radius": 18,
-    "spacing": 12
-  },
-  "app_bar": {
-    "title": "학교 생활",
-    "subtitle": "{{data.today.summary}}",
-    "pinned": true,
-    "actions": [
-      {
-        "id": "settings",
-        "label": "설정",
-        "icon": "settings",
-        "show_as": "overflow",
-        "action": {"type": "navigate", "target": "school_life.settings"}
-      }
-    ]
-  },
-  "navigation": {
-    "type": "adaptive",
-    "selected_state_key": "section",
-    "persist": true,
-    "label_behavior": "selected",
-    "items": [
-      {
-        "id": "today",
-        "label": "오늘",
-        "icon": "calendar",
-        "value": "today",
-        "action": {"type": "set_state", "values": {"section": "today"}}
-      },
-      {
-        "id": "week",
-        "label": "이번 주",
-        "icon": "clock",
-        "value": "week",
-        "action": {"type": "navigate", "target": "school_life.week"}
-      }
-    ]
-  },
-  "initial_state": {"section": "today"},
-  "data_sources": [
-    {
-      "id": "today",
-      "capability": "school_life.today",
-      "trigger": "load",
-      "query": null,
-      "arguments": {},
-      "refresh_seconds": 300
-    }
-  ],
-  "view": {
-    "type": "column",
-    "props": {"spacing": 12},
-    "children": [
-      {"type": "text", "props": {"text": "{{data.today.summary}}", "style": "heading"}}
-    ]
-  }
-}
-```
-
-허용 config 필드는 `ui_schema`, `icon`, `description`, `placement`, `app_bar`, `navigation`,
-`theme`, `initial_state`, `data_sources`, `view`입니다.
-
-## 트리와 크기 제한
-
-- tree 최대 160 node, depth 12(root가 depth 0), node당 child 최대 32개
-- data source 최대 8개
-- state key 최대 32개
-- config JSON 최대 32 KiB
-- 자동 refresh 30~86,400초
-- 한 extension의 app bar action 최대 6개
-- navigation item 2~8개
-- binding 깊이 최대 12 segment
-- JSON binding 값 깊이 최대 8, 배열·객체 항목 최대 64개
-
-`positioned`, `scroll`, `padding`, `center`, `expanded`, `badge`는 child를 정확히 하나만 가집니다.
-`surface`는 child가 하나 이상이어야 합니다. `positioned`는 `stack`의 직접 child이고 `left`, `top`,
-`right`, `bottom` 중 하나 이상을 지정해야 합니다. `expanded`는 `row` 또는 `column`의 직접
-child입니다.
-
-크기 prop은 0~4096, position offset은 -4096~4096, spacing과 inset은 0~128입니다.
-`border_width` 0~8, `border_radius` 0~64, `elevation` 0~24, `opacity` 0~1,
-`aspect_ratio` 0.1~20, `flex` 1~24를 사용합니다. `padding`과 `margin`의 정확한 입력 형태와
-theme 색상 역할은 [토큰과 반응형](design-tokens-responsive.md)에 있습니다.
-
-## Plugin Theme
-
-theme를 생략한 기존 플러그인은 Morit의 현재 Material 3 라이트·다크 theme를 그대로 상속합니다.
-선택적으로 base와 mode별 일부 값만 재정의할 수 있고 누락 값은 항상 Host 값으로 채웁니다.
-
-```json
-{
-  "theme": {
-    "radius": 18,
-    "typography": {"scale": 1.0, "body_weight": 400, "title_weight": 700},
-    "surface": {"elevation": 1},
-    "border": {"width": 1, "radius": 18},
-    "icon": {"size": 22},
-    "states": {"disabled_opacity": 0.38},
-    "light": {
-      "color_scheme": {
-        "primary": "#315DA8",
-        "on_primary": "#FFFFFF",
-        "surface": "#F9F9FF",
-        "on_surface": "#1A1B20"
-      }
-    },
-    "dark": {
-      "color_scheme": {
-        "primary": "#AFC6FF",
-        "on_primary": "#002F66",
-        "surface": "#111318",
-        "on_surface": "#E2E2E9"
-      },
-      "states": {"selected_color": "primary_container"}
-    }
-  }
-}
-```
-
-지원 그룹은 `color_scheme`, `typography`, `surface`, `border`, `icon`, `states`, `radius`,
-`spacing`, `density`와 최상위 `light`, `dark`입니다. mode variant 안에 다시 `light`/`dark`를 중첩할
-수 없습니다. 명백히 같은 literal 전경/배경은 validate 오류이고, 계산 가능한 대비가 4.5:1보다
-낮으면 경고합니다. semantic token이나 Host 상속 때문에 정적으로 확정할 수 없는 조합은 Preview와
-실제 앱에서 확인합니다.
-
-## State
-
-`initial_state`가 허용 state key와 초기값을 선언합니다. key는 영문자로 시작하고 영문·숫자·밑줄을
-사용하는 최대 64자입니다.
-
-```json
-{
-  "initial_state": {"period": "today", "notifications": true}
-}
-```
-
-`field`, `select`, `switch`, navigation selection, `set_state`는 여기에 선언된 key만 변경합니다.
-`persist: true`는 Instance settings의 extension 전용 namespace에 저장합니다. credential과 민감한
-사용자 데이터는 state에 저장하지 않습니다.
-
-## Data source와 binding
-
-```json
-{
-  "id": "schedule",
-  "capability": "school_life.schedule",
-  "trigger": "load",
-  "query": "{{state.period}}",
-  "arguments": {"period": "{{state.period}}"},
-  "refresh_seconds": 300
-}
-```
-
-`trigger`는 `load` 또는 `manual`입니다. 결과는 다음 namespace로 읽습니다.
-
-```text
-data.<source_id>.completed
-data.<source_id>.summary
-data.<source_id>.data.<field>
-```
-
-반복 template 안에서는 `item.<field>`를 사용합니다. 문자열 전체가 binding 하나면 원래 JSON type을
-arguments에 전달하고, 다른 글자와 섞으면 텍스트 template이 됩니다.
-
-```json
-{"limit": "{{state.limit}}"}
-```
-
-```json
-{"label": "{{state.period}} 일정"}
-```
-
-### Local Storage binding
-
-저장소도 같은 data source/action 흐름을 사용합니다.
-
-```json
-{
-  "id": "tasks",
-  "capability": "morit.storage.list",
-  "trigger": "load",
-  "query": "",
-  "arguments": {"namespace": "tasks", "limit": 20}
-}
-```
-
-`list.source`에는 `data.tasks.data.items`를 사용합니다. Storage mutation이나 AI 응답 완료 뒤 Host가
-Storage source만 갱신하며 앱 재개 시에도 최신 값을 읽습니다. CRUD, 권한과 migration은
-[Plugin Local Storage와 AI 접근](plugin-storage.md)을 참고하세요.
-
-### Capability 결과 이미지
-
-`image`와 `avatar`의 `url`은 literal URL이 아니라 capability 결과를 가리키는 전체
-`{{data.<source>...}}` 또는 `{{item...}}` binding입니다. Manifest가 `network`를 요청하고 활성
-Instance가 `network`를 grant한 경우에만 표시할 수 있습니다.
-
-Host renderer는 해석된 URL을 앱에서 직접 fetch하지 않고 인증된
-`POST /v1/plugin-instances/{instance_id}/ui-images:fetch`를 사용합니다. 요청 body는 다음과 같습니다.
-
-```json
-{"url": "https://images.example.edu/today.png"}
-```
-
-Host proxy는 공개 HTTPS와 SSRF 정책을 적용하고 redirect를 따르지 않습니다. PNG/JPEG/GIF/WebP만
-허용하며 응답 MIME type, magic byte, 실제 이미지 포맷이 모두 일치해야 합니다. 응답 본문은 최대
-512 KiB, 가로·세로는 각각 최대 4096 px입니다. 정적 이미지는 1 frame, 애니메이션은 최대 128
-frame이며 `width × height × frame 수`로 계산한 frame 합산 pixel은 최대 16,000,000입니다. 검증
-실패는 해당 이미지 fallback으로 격리하며 원본 URL이나 실패 응답을 직접 렌더링하지 않습니다.
-
-## App bar
-
-`app_bar`는 Host 화면 chrome을 구성합니다. tree 안에 앱 바를 다시 만들지 않습니다.
-
-| 필드 | 규칙 |
-|---|---|
-| `title` | 필수, binding 가능, 최대 120자 |
-| `subtitle` | 선택, binding 가능, 최대 160자 |
-| `center_title`, `pinned` | boolean |
-| `leading` | action item 하나 |
-| `actions` | 최대 6개 |
-
-action item은 `id`, `label`, 선택적 `icon`, `show_as`, 필수 `action`을 가집니다. `show_as`는
-`auto`, `always`, `overflow`입니다. overflow에는 드문 행동을 두고 주요 행동은 화면 본문에 둡니다.
-
-## Navigation
-
-`navigation.type`은 `tabs`, `bar`, `rail`, `drawer`, `adaptive`입니다. 각 item은 `id`, `label`,
-선택적 `icon`, `selected_icon`, `value`, 필수 `action`을 가집니다.
-
-`selected_state_key`를 사용하면 해당 key가 `initial_state`에 있어야 하고 모든 item에 `value`가
-필요합니다. `label_behavior`는 `auto`, `always`, `selected`, `never`입니다. `rail_breakpoint`는
-480~1600입니다.
-
-## Component tree
-
-지원 node:
-
-```text
-column row wrap grid stack positioned scroll padding center expanded
-surface card section text icon image avatar badge divider spacer
-button chip metric progress list timeline calendar chart
-form dialog sheet field select switch empty
-```
-
-각 node의 목적과 props는 [컴포넌트 레퍼런스](components.md), 색·크기 범위는
-[토큰과 반응형](design-tokens-responsive.md)을 참고하세요.
-
-## Action
-
-### Capability 실행
-
-```json
-{
-  "type": "invoke",
-  "capability": "school_life.lookup",
-  "query": "{{state.query}}",
-  "arguments": {"limit": 10},
-  "store": "results"
-}
-```
-
-`store`는 선언된 data source ID이며 성공 결과로 해당 source를 교체합니다.
-
-### State와 refresh
-
-```json
-{"type": "set_state", "values": {"period": "tomorrow"}, "persist": true}
-```
-
-```json
-{"type": "refresh", "source": "schedule"}
-```
-
-### Navigation
-
-```json
-{
-  "type": "navigate",
-  "target": "school_life.details",
-  "transition": "platform",
-  "replace": false
-}
-```
-
-`transition`은 `platform`, `fade`, `slide`, `none`입니다. `replace: true`는 현재 route를 뒤로가기
-stack에서 교체합니다. 같은 manifest의 UI extension ID만 target이 될 수 있습니다.
-
-```json
-{"type": "back"}
-```
-
-## 조건부 표시
-
-```json
-{
-  "visible_when": {
-    "path": "data.schedule.data.items",
-    "exists": true
-  }
-}
-```
-
-`equals`, `not_equals`, `exists` 중 정확히 하나를 사용합니다. 조건은 state·data·현재 `item` 값만
-읽고 임의 expression을 실행하지 않습니다.
-
-## 로딩과 오류 복구
-
-Host는 source별 실행을 격리하고 중복 실행을 합칩니다. 화면이 background로 가면 자동 refresh를
-멈추고 다시 foreground가 될 때 최신 source를 확인합니다. 갱신 실패 시 기존 정상 데이터가 있으면
-유지하고, 첫 로드도 실패한 경우에만 해당 영역에 retry 상태를 표시합니다. package generation이나
-화면이 바뀐 뒤 도착한 오래된 응답은 버립니다.
-
-## Response UI
-
-`point: "response"`도 같은 `theme`, `app_bar`, `navigation`, data/state/node/action 계약을
-재사용합니다. 추가로 `a2ui.version`, 사용 조건을 설명하는 `a2ui.description`, 실제 Tool 결과를
-검증할 `a2ui.schema`가 필수입니다. 결과는 AI가 catalog 후보를 명시적으로 선택하고 Host의
-유효성·관련성·중복·권한 검증을 통과했을 때만 해당 AI 메시지의 한 response container 안에
-렌더링됩니다. 서버는 response를 일괄 생성하거나 shape로 추측하지 않습니다. 상세 계약과 기본
-catalog는 [Response UI와 Agent Timeline](ai-response-and-timeline.md)을 참고하세요.
-
-## Preview와 실제 Host
-
-`morit plugin preview . --output ./dist/preview.html` 또는 `morit_project_preview`는 validate를 먼저
-통과한 config를 실행 코드 없이 안전한 HTML로 렌더링합니다. 상단 토글로 light/dark variant와 Host
-상속 결과를 비교할 수 있습니다. 같은 manifest를 Flutter 앱이 실제 Material widget으로 렌더링하므로
-node, binding, theme 계약은 공유하지만 focus, 키보드, route stack, 권한, 실제 Tool 호출은 서명
-package를 앱에 설치해 최종 확인합니다.

package/assets/docs/verification.md

@@ -1,133 +0,0 @@
-# 예제 검증 방법과 확인 경계
-
-자동 테스트, 외부 서비스 live test, Android 실기기 확인은 서로 다른 증거입니다. 하나의 성공을
-다른 단계의 성공으로 기록하지 않습니다. 실행 시각, 대상 version, 명령, 종료 코드, artifact
-SHA-256을 함께 남기면 나중에 같은 결과를 재현할 수 있습니다.
-
-## 1. 패키지 무결성
-
-현재 저장소의 예제 artifact는 다음과 같습니다.
-
-| 패키지 | 크기 | SHA-256 |
-|---|---:|---|
-| `school-life-1.5.0.mplg` | 263433 bytes | `0939f8956037638d56f7672ac4f9c4d8f6472d58d23840c1fd5baab198c41e29` |
-| `notion-1.1.0.mplg` | 3044 bytes | `eba57c440b305343c5cf917259e30e50b322272cfadb0ed64d39ecfc47539c4e` |
-
-```powershell
-python tools/morit_plugin.py verify `
-  examples/plugins/school-life/dist/school-life-1.5.0.mplg
-python tools/morit_plugin.py verify `
-  examples/plugins/notion/dist/notion-1.1.0.mplg
-Get-FileHash -Algorithm SHA256 @(
-  'examples/plugins/school-life/dist/school-life-1.5.0.mplg',
-  'examples/plugins/notion/dist/notion-1.1.0.mplg'
-)
-```
-
-`verify`는 ZIP 안전성, canonical payload, embedded Ed25519 public key와 signature를 검사합니다.
-검증 결과에 publisher key가 포함되어 있어야 하며, trusted publisher 사전 등록 여부와 무관하게
-서명 자체가 유효해야 합니다. Host의 신뢰 정책은 설치·실행 단계에서 별도로 적용됩니다.
-
-문서의 hash는 source나 build 규칙이 바뀌면 달라집니다. 새 artifact를 만들었으면 위 명령으로
-실제 파일을 다시 계산한 뒤 문서와 배포 metadata를 함께 갱신합니다.
-
-## 2. 자동 회귀 테스트
-
-저장소 root에서 다음 검사를 먼저 실행합니다.
-
-```powershell
-npx -y @morit/cli plugin validate .\examples\plugins\school-life
-npx -y @morit/cli plugin validate .\examples\plugins\notion
-python -m unittest discover -s backend/archive_processing -p "test_*.py"
-python -m unittest discover -s backend/plugin_mcp -p "test_*.py"
-dart analyze
-flutter test
-```
-
-관련 backend 테스트는 정상 package 설치·복원·삭제, actor 격리, permission/readiness gate,
-Connection OAuth state와 replay 차단, credential 암호화·갱신·해제, host-action outbox,
-Slash·Search·Tool routing, UI/Response 계약을 검사합니다. transport fixture 테스트는 외부 서비스가
-응답하지 않아도 request/response parser 계약을 확인하지만 실제 사용자 계정의 성공을 증명하지는
-않습니다.
-
-## 3. Backend live E2E
-
-`tools/plugin_live_e2e.py`는 임시 Supabase 사용자를 만들고 공개 API를 호출합니다. 관리자 key를
-사용하므로 승인된 운영자 환경에서만 실행하며 Secret, OAuth code, access token을 로그에 남기지
-않습니다.
-
-```powershell
-$env:MORIT_E2E_ENV = 'C:\secure\morit-backend.env'
-$env:MORIT_E2E_API = 'https://morit-api.moring.co'
-$env:MORIT_SCHOOL_PLUGIN = 'examples/plugins/school-life/dist/school-life-1.5.0.mplg'
-$env:MORIT_NOTION_PLUGIN = 'examples/plugins/notion/dist/notion-1.1.0.mplg'
-
-# 실제 Notion 승인을 할 때만 0보다 큰 값을 사용합니다.
-$env:MORIT_E2E_WAIT_NOTION_OAUTH_SECONDS = '300'
-$env:MORIT_E2E_NOTION_QUERY = 'Morit 프로젝트'
-$env:MORIT_E2E_NOTION_PAGE_QUERY = 'Morit 프로젝트 안내'
-$env:MORIT_E2E_NOTION_DATA_SOURCE_QUERY = 'Morit 작업 목록'
-
-python tools/plugin_live_e2e.py
-```
-
-live E2E에서 확인할 핵심 순서는 다음과 같습니다.
-
-1. 신규 사용자의 설치·Instance 목록이 비어 있고 traversal package가 부분 상태 없이 차단됨
-2. 학교와 Notion package를 함께 설치하면 각 설치의 기본 Instance가 정확히 하나 생성됨
-3. 권한 승인 전 capability가 노출되지 않고, 승인 후 학교 Tool·Search·Slash·background가 등록됨
-4. 실제 NEIS 조회, 검색, 알림 outbox lease/ACK, 재시작 후 registry 복원이 동작함
-5. Notion 승인 시 기본 Instance의 Connection이 활성화되고 실제 page/data source를 읽음
-6. Connection 삭제 후 credential을 다시 쓰지 않으며 capability가 즉시 제거됨
-7. disable/delete/purge 뒤 cache, 설정, credential, pending action이 남지 않음
-
-같은 외부 서비스를 여러 계정으로 쓰는 경우 설치나 root Instance를 복제하지 않습니다. 하나의
-기본 Instance 아래 여러 Connection을 만들고 `allow_multiple` 정책과 계정별 격리를 검사합니다.
-
-스크립트 결과는 다음처럼 해석합니다.
-
-| 출력 | 종료 코드 | 의미 |
-|---|---:|---|
-| `backend_live_plugin_e2e=passed` | 0 | 요청한 외부 단계까지 모두 확인 |
-| `backend_live_plugin_e2e=partial reasons=...` | 2 | 일부 외부 승인·재시작 단계가 빠짐 |
-| `backend_live_plugin_e2e=failed ...` | 1 | 구현·배포·API 검증 실패 |
-
-Notion 사용자 승인을 생략했거나 운영 process 재시작 명령을 주지 않은 실행은 `partial`입니다.
-`state=completed`나 검색 결과 수만으로 page/data source 본문 조회 성공을 추정하지 않습니다.
-
-## 4. Android 실기기 확인
-
-Backend live test는 앱 화면과 Android 알림을 누르지 않습니다. release APK를 실제 기기에 설치해
-다음을 별도로 확인합니다.
-
-1. `.mplg` 파일 선택 후 설치·권한·초기 설정 흐름
-2. 학교 후보 선택, 오늘·주간·급식 화면과 빈 상태·오류 상태
-3. Notion 공식 승인, Connection 추가·전환·해제와 실제 page/data source 표시
-4. AI 자연어·Slash·Search와 해당 AI 메시지 안의 Response UI
-5. 알림 권한 승인 후 실제 알림 표시
-6. 강제 종료·재실행 뒤 설치·연결·화면 상태 복원
-7. 비활성화·삭제 뒤 화면·capability·알림 제거
-
-Response UI는 정상 데이터에서 필요한 컴포넌트 하나만 선택되는지뿐 아니라 빈 데이터, 관련 없는
-질문, 같은 결과의 중복, schema 불일치, 권한 미승인, Tool 실패에서 컴포넌트가 생성되지 않고 일반
-텍스트 답변이 유지되는지도 확인합니다. Plugin Response는 `plugin.<extension-id>` 등록 ID와 실제
-실행 capability의 data source가 일치해야 합니다.
-
-실기기에서 확인하지 않은 항목은 자동 테스트가 통과했더라도 `미검증`으로 남깁니다.
-
-## 5. 결과 기록 형식
-
-```text
-시각(KST):
-source revision:
-Plugin/Host version:
-실행 명령과 종료 코드:
-artifact 경로·크기·SHA-256:
-자동 테스트:
-live E2E:
-Android/iOS/Desktop 실기기:
-생략 또는 실패한 단계와 이유:
-```
-
-성공 기록에는 실행하지 않은 항목을 넣지 않습니다. iOS·Desktop은 현재 Host 지원 범위를 먼저
-확인하고, 지원이 확정되지 않은 플랫폼을 Android 결과로 대신하지 않습니다.