@morit/cli 1.3.0 → 1.4.2

package/assets/docs/ai-response-and-timeline.md

@@ -1,203 +0,0 @@
-# Response UI와 Agent Timeline
-
-Response UI는 capability 결과를 AI 메시지 안에서 시각화합니다. 대화 아래의 별도 카드 목록이나
-overflow 메뉴 밑에 떨어뜨리지 않고, 해당 AI 메시지에 속한 하나의 response container 안에
-제목·내용·행동을 함께 렌더링합니다.
-
-## Response extension
-
-```json
-{
-  "id": "school_life.day_response",
-  "point": "response",
-  "title": "오늘 학교 생활",
-  "order": 10,
-  "permissions": [],
-  "config": {
-    "ui_schema": 2,
-    "a2ui": {
-      "version": "v0.9",
-      "description": "수업 정보가 실제 답변에 필요하고 표시할 항목이 있을 때만 사용합니다.",
-      "schema": {
-        "type": "object",
-        "properties": {
-          "timetable": {
-            "type": "array",
-            "items": {"type": "object"},
-            "minItems": 1,
-            "maxItems": 12
-          }
-        },
-        "required": ["timetable"],
-        "additionalProperties": true
-      }
-    },
-    "theme": {"density": "compact"},
-    "data_sources": [
-      {
-        "id": "result",
-        "capability": "school_life.schedule.lookup",
-        "trigger": "manual",
-        "query": "",
-        "arguments": {}
-      }
-    ],
-    "view": {
-      "type": "column",
-      "props": {"spacing": 10},
-      "children": [
-        {
-          "type": "text",
-          "props": {"text": "{{data.result.summary}}", "style": "heading"}
-        },
-        {
-          "type": "timeline",
-          "props": {"source": "data.result.data.timetable", "empty_text": "수업 정보가 없습니다."},
-          "children": [
-            {
-              "type": "text",
-              "props": {"text": "{{item.period}}교시 · {{item.subject}}"}
-            }
-          ]
-        }
-      ]
-    }
-  }
-}
-```
-
-Response point도 일반 Runtime v2와 같은 node, theme, app bar, navigation, binding, action 계약을
-사용합니다. Host가 선택·검증한 capability 결과는 `data` namespace에 주입되므로 같은 결과를 얻기
-위해 화면 mount 시 외부 요청을 반복하지 않습니다. 후속 refresh나 사용자가 누른 action에만 추가
-capability를 호출합니다. 기존 `a2ui` 선언이 없는 Response extension은 지원하지 않습니다.
-
-## AI 선택과 Host 검증
-
-서버는 모든 Tool 결과에 UI를 일괄 생성하거나 데이터 key로 컴포넌트를 추측하지 않습니다. 최종
-답변 모델이 현재 답변에 실제 도움이 되는 후보의 `candidate_id`와 `component`만 선택합니다. 모델은
-컴포넌트 데이터나 임의 ID를 만들 수 없고, 실제 Tool 결과는 Host가 선택 뒤 주입합니다.
-
-선택 뒤 Host는 다음을 모두 통과한 항목만 A2UI v0.9 DataPart로 저장하고 해당 AI 메시지에 붙입니다.
-
-- 실행 상태가 `completed` 또는 `partial`이고 실제 값이 있음
-- 질문·최종 답변과 capability 결과가 관련됨
-- 같은 데이터의 Response UI가 이미 선택되지 않음
-- 기본 컴포넌트별 필수 값과 URL 형식이 유효함
-- Plugin 컴포넌트의 schema, A2UI version, 설치 상태, Instance 권한과 capability 연결이 유효함
-
-빈 데이터, 실패한 Tool, 무관하거나 중복된 결과, 불확실한 선택은 UI를 만들지 않습니다. 선택 모델
-호출이나 렌더링이 실패해도 일반 텍스트 답변은 그대로 완료됩니다. 진행·실패 상태는 Agent Timeline에
-표시하며 의미 없는 loading/failed Response 카드를 미리 만들거나 DB에 남기지 않습니다.
-
-## 기본 A2UI Component Catalog
-
-| component | 표시 조건 |
-|---|---|
-| `weather` | 현재 기온·상태 또는 예보가 하나 이상 유효함 |
-| `chart` | label과 수치가 있는 행이 2개 이상임; `bar`, `line`, `pie`, `scatter` |
-| `image_gallery` | HTTPS 이미지와 원문 URL·출처명이 함께 있음 |
-| `exchange_rate` | 기준 통화, 상대 통화, 유한한 환율 값이 있음 |
-| `article_list` | 제목·출처·원문이 있는 서로 다른 기사 2개 이상 |
-| `article_card` | 제목·출처·게시 시각·요약·본문 일부·이미지·원문이 모두 있음 |
-| `file_result` | 실제 Morit item ID 또는 검증 가능한 다운로드 URL이 있음 |
-| `image_preview` | 실제 image item 또는 검증 가능한 preview URL이 있음 |
-| `video_preview` | 실제 video item/URL과 thumbnail URL이 함께 있음 |
-
-각 renderer도 같은 필수 값을 다시 확인하고, 값이 바뀌거나 손상되면 해당 컴포넌트만 fallback합니다.
-
-## Plugin 컴포넌트의 동적 등록
-
-활성 Instance의 `point: "response"` extension은 capability 실행 시
-`plugin.<extension-id>` 이름으로 현재 A2UI catalog에 동적 등록됩니다. AI에게는 Host가 확인한 ID,
-설명, version, schema만 노출됩니다. `a2ui.schema`는 root `object`인 안전한 JSON Schema 부분집합이며
-`type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, 문자열·숫자·배열 bound를
-지원합니다. schema는 최대 16 KiB, 깊이 6이며 object/list는 각 64개로 제한됩니다.
-
-Plugin Response는 Runtime v2의 전체 layout, surface, theme, image, action과 binding을 사용할 수
-있습니다. 단, extension 권한은 Manifest grant의 부분집합이어야 하고 `data_sources` 중 하나가 실제
-실행 capability를 가리켜야 합니다. 패키지 설치, CLI validate, Host 로드, Flutter parse와 표시 직전
-검증이 같은 규칙을 사용합니다.
-
-## 한 container의 정보 순서
-
-1. 결과를 설명하는 짧은 제목 또는 summary
-2. 사용자가 요청한 핵심 데이터
-3. 출처·기간·갱신 시점 같은 보조 정보
-4. 필요한 후속 행동 1~2개
-
-복사, 다시 시도, 다운로드 같은 메뉴도 같은 container의 Host chrome에 속합니다. 각 section을
-별도 떠 있는 card로 만들지 않습니다. 긴 결과는 list limit과 상세 화면 이동을 사용합니다.
-
-## 대화 UI를 깨뜨리지 않는 제약
-
-- 메시지 폭을 넘는 고정 width를 사용하지 않습니다.
-- Response 내부에 자체 채팅 입력창을 만들지 않습니다.
-- 무한 높이 목록 대신 요약과 상세 화면 이동을 제공합니다.
-- background refresh가 대화 scroll 위치를 바꾸지 않게 기존 높이와 데이터를 가능한 유지합니다.
-- 렌더링 오류는 해당 Response만 텍스트 fallback으로 바꾸고 대화 전체를 종료하지 않습니다.
-- accessibility 순서는 AI 본문 다음, Response 제목, 내용, 행동 순으로 유지합니다.
-
-## Text fallback
-
-Response UI를 표시할 수 없더라도 AI의 원래 텍스트 답변은 남아야 합니다. capability는 UI 전용
-원시 JSON만 반환하지 말고 사람이 읽을 수 있는 `summary`를 함께 제공합니다. 빈 배열만 있거나
-schema가 맞지 않으면 UI를 억지로 채우지 않습니다. 알 수 없는 node, 손상된 binding, 이미지 로드
-실패는 전체 답변 성공을 숨기지 않습니다.
-
-```json
-{
-  "completed": true,
-  "summary": "오늘은 6교시이며 점심은 카레라이스입니다.",
-  "data": {
-    "timetable": [],
-    "meal": {}
-  },
-  "evidence": []
-}
-```
-
-## Agent Timeline
-
-Agent Timeline은 모델의 숨겨진 추론이 아니라 사용자가 이해할 수 있는 실행 상태만 보여줍니다.
-
-```text
-요청을 확인하고 계획했어요
-  ├─ 학교 정보를 확인했어요
-  ├─ 오늘 시간표를 불러왔어요
-  └─ 결과를 정리했어요
-```
-
-Timeline event에는 도구 이름이나 내부 stack trace 대신 작업 이름, 상태, 필요한 사용자 행동을
-기록합니다. 상태는 대체로 다음과 같습니다.
-
-- 진행 중
-- 완료
-- 재시도 중
-- 사용자 입력 필요
-- 일부 결과로 완료
-- 실패
-
-Tool 하나가 실패했지만 대체 경로로 결과를 만들었다면 전체 timeline을 실패로 표시하지 않습니다.
-실패한 단계와 복구 결과를 함께 설명합니다.
-
-## Code Interpreter 파일
-
-Code Interpreter가 파일을 만들었다면 sandbox 내부 경로만 답변에 남기지 않습니다. 파일은 Host가
-접근 가능한 artifact로 전달되고, AI 답변에는 실제 파일 이름·형식·크기와 다운로드 가능한 링크가
-있어야 합니다. Response UI의 다운로드 action은 동일 artifact를 가리키며 존재하지 않는 경로나
-가짜 링크를 생성하지 않습니다.
-
-파일 생성 완료 조건은 [AI Skill과 파일 산출물](ai-skill-and-docx-workflow.md)에 정리되어 있습니다.
-
-## 이미지 artifact
-
-`image_generation`·`image_edit`의 PNG/JPEG/GIF/WebP artifact는 생성 중 placeholder에서 완료 후 답변
-내 inline 이미지로 바뀝니다. 여러 장은 gallery로 넘기며 원본 비율을 유지한 contain 렌더링,
-전체 화면 `InteractiveViewer`, 다운로드, Android 공유를 제공합니다. 대화 재진입 때도 저장된
-`ai_tool_executions.result_summary.artifacts`를 다시 사용합니다.
-
-Artifact URL은 conversation·execution·attachment 소유권을 확인한 뒤 5분 signed URL로 만들며 만료나
-일시 실패 시 새 URL을 받아 두 번 시도합니다. 앱은 redirect를 따르지 않고 HTTPS(개발 loopback 제외),
-MIME, magic byte, 실제 decode, 24 MiB, 4096 px, 16 MP를 확인합니다. SVG와 외부 실행 형식은 inline으로
-열지 않고 기존 파일 카드로 fallback합니다. Plugin response의 URL 이미지는 앱이 직접 요청하지 않고
-기존 인증 Host proxy와 `network` grant를 거치며 실패 시 이미지 단위 재시도를 제공합니다.

package/assets/docs/ai-skill-and-docx-workflow.md

@@ -1,83 +0,0 @@
-# AI Skill과 파일 산출물
-
-Morit Plugin의 `kind: "skill"`과 Codex·Claude 같은 AI 에이전트의 Skill 파일은 이름이 같지만
-역할이 다릅니다.
-
-- Morit Plugin Skill: Host가 설치·권한·timeout 경계에서 실행하는 capability
-- AI 에이전트 Skill: 에이전트가 작업 순서와 도구 사용법을 따르는 지침
-
-에이전트 Skill을 사용해 플러그인을 만들더라도 결과 `.mplg`는 일반 SDK 계약과 동일하게 검증·서명됩니다.
-
-## 파일 작업 완료 순서
-
-문서, 표, 이미지, archive 등 파일을 만드는 capability나 AI 작업은 다음 순서를 지킵니다.
-
-```text
-요청과 입력 조사
-  → 파일 생성·편집
-  → 구조 검증
-  → 가능하면 시각 검증
-  → 원래 parser로 다시 열고 내용 확인
-  → 최종 artifact 저장
-  → 사용자에게 실제 링크와 요약 반환
-```
-
-“작업을 마쳤어요”만 답하거나 sandbox 내부 경로만 남기면 완료가 아닙니다. 존재하지 않는 `.docx`
-경로나 아직 생성하지 않은 artifact를 최종 링크처럼 반환하지 않습니다.
-
-## DOCX 예
-
-DOCX는 Microsoft Open XML ZIP 구조입니다. 단순히 `.docx` 확장자를 붙이지 않습니다.
-
-1. 요청한 목차, 표, 이미지, 스타일을 실제로 작성합니다.
-2. ZIP entry와 `[Content_Types].xml`, document relationship을 확인합니다.
-3. DOCX parser로 다시 열어 문단·표·이미지 수를 확인합니다.
-4. 모든 페이지를 렌더링해 잘림, 빈 페이지, 겹침, 깨진 한글을 확인합니다.
-5. 수정 후 parser와 렌더링을 다시 실행합니다.
-6. 존재하고 0바이트가 아닌 최종 `.docx`만 artifact로 반환합니다.
-
-다른 형식도 동일합니다. PDF는 모든 페이지, spreadsheet는 수식과 셀 type, image는 실제 크기와
-디코딩, ZIP은 entry 경로와 traversal 안전성을 확인합니다.
-
-## Plugin이 파일을 만드는 경우
-
-Plugin은 `file_write` 권한을 요청하고 Host가 제공하는 artifact 경계로 결과를 전달합니다.
-`sandbox_python` 응답의 `summary`, `data`, `evidence`에 존재하지 않는 `sandbox:/...` 링크를 만들지
-않습니다. Host로 복사된 artifact ID나 내부 파일 링크 문법을 사용하고, AI 최종 답변에는 다음을
-포함합니다.
-
-- 파일 이름과 형식
-- 사용자가 요청한 결과 요약
-- 다운로드 또는 앱 내부 미리보기 링크
-- 검증한 항목과 남은 제한
-
-## `.mplg` 산출물
-
-플러그인 개발도 파일 작업입니다.
-
-```text
-source 작성
-  → validate
-  → UI가 있으면 preview
-  → signed build
-  → package reopen·signature verify
-  → 앱 설치·실행
-  → 요청한 경로에 artifact 반환
-```
-
-source ZIP과 `.mplg`는 목적이 다릅니다. source ZIP은 편집용이고 `.mplg`는 설치용입니다. 둘을 같은
-다운로드 이름이나 MIME으로 반환하지 않습니다.
-
-플러그인의 기본 품질 게이트는 `validate → preview → build → verify`입니다. UI가 없는 package는
-preview를 생략할 수 있지만 생략 이유를 결과에 기록합니다.
-
-## 완료 체크
-
-- 요청한 모든 파일이 실제로 존재하는가
-- 파일 크기가 0보다 큰가
-- 확장자와 내부 형식이 일치하는가
-- 원래 parser로 다시 열리는가
-- 모든 페이지/시트/entry를 확인했는가
-- 미리보기와 다운로드가 같은 최종 artifact를 가리키는가
-- sandbox 경로나 secret이 사용자 응답에 남지 않았는가
-- 실패한 Tool이 있다면 복구·대체 결과와 제한을 설명했는가

package/assets/docs/app-builder.md

@@ -1,56 +0,0 @@
-# 앱에서 플러그인 만들기
-
-Plugin Builder는 개발 환경 없이 작은 Tool 또는 Skill을 만드는 경로입니다. Builder도 일반
-`.mplg`를 생성하고 같은 설치·권한·삭제 흐름을 사용하지만, 안전하게 표현할 수 있는 범위를
-의도적으로 제한합니다.
-
-## 지원 범위
-
-| 항목 | 지원 값 |
-|---|---|
-| capability kind | `tool`, `skill` |
-| runtime | `text_stats`, `text_template` |
-| UI 위치 | `card`, `screen`, `settings` 중 최대 3개 |
-| 선택 기능 | Search Provider, Slash Command, background, notification |
-| 권한 | `background`, `notifications` |
-| credential | 최대 4개의 `api_token` 선언(현재 앱 화면은 고급 source 흐름에서 설정) |
-| background 주기 | 15~10,080분 |
-
-Builder는 ID, 이름, 설명, version, capability 제목과 runtime 설정을 입력받아 최소 Manifest와
-Runtime v1 UI를 만듭니다. UI 코드를 생성하거나 외부 코드를 실행하지 않습니다.
-
-## Builder가 적합한 예
-
-- 입력 텍스트의 길이와 단어 수를 계산하는 Tool
-- 정해진 템플릿으로 회의 메모를 정리하는 Skill
-- settings의 작은 정적 목록을 Search Provider로 노출
-- 정해진 문구를 일정 주기로 알리는 개인 알림
-
-## 소스 프로젝트로 전환할 때
-
-다음 중 하나가 필요하면 공식 CLI 프로젝트를 사용합니다.
-
-- Runtime v2의 화면·내비게이션·theme·Response UI
-- 외부 HTTPS API, OAuth, Remote MCP
-- 여러 데이터 source와 동적 목록
-- `sandbox_python` 데이터 처리
-- child package와 dependency
-- Cloud Secret, Connector retry/rate-limit
-- package asset, 이미지, 복수 source file
-
-[시작하기](getting-started.md)의 `@morit/cli plugin setup`으로 프로젝트를 만들고 Builder에서 정한
-ID와 capability 이름을 유지하면 사용자가 기능을 다시 익힐 필요가 없습니다. 기존 설치를 업데이트할
-때는 publisher와 서명 identity, plugin ID, semantic version 순서를 유지해야 합니다.
-
-## 실제 확인
-
-Builder 생성 성공만 확인하지 말고 다음을 앱에서 실행합니다.
-
-1. 생성 직후 설치 목록에 나타나는지
-2. 필요한 권한을 거부했을 때 기능이 실행되지 않는지
-3. Tool/Skill과 Slash Command가 정확한 capability를 호출하는지
-4. background/notification을 켜고 끌 수 있는지
-5. 설정 변경 후 다시 열었을 때 유지되는지
-6. 삭제 후 pending 알림과 credential이 정리되는지
-
-고급 화면 개발은 [화면, 레이아웃, 내비게이션](screens-layout-navigation.md)부터 시작하세요.

package/assets/docs/authentication.md

@@ -1,140 +0,0 @@
-# 외부 서비스 인증과 Cloud Secrets
-
-플러그인 source와 `.mplg`에는 비밀 값이 들어가지 않습니다. package는 필요한 Credential·Connector·
-Secret ID만 선언하고 실제 값은 사용자 Connection 또는 조직의 Cloud Secret에 저장합니다.
-
-## 선택 기준
-
-| 값의 소유자 | 사용 모델 | 예 |
-|---|---|---|
-| 각 사용자 | Credential + Connection | 개인 Notion OAuth, 개인 API token |
-| Developer 조직 | Cloud Secret | 서버 간 API key, OAuth client secret |
-| 공개 설정 | Connector 또는 manifest | 공개 HTTPS endpoint, provider ID |
-
-사용자 token을 Cloud Secret으로 공유하거나 조직 secret을 Instance settings에 복사하지 않습니다.
-
-## Manifest 선언
-
-OAuth 계정:
-
-```json
-{
-  "credentials": [
-    {
-      "id": "notion_account",
-      "label": "Notion 계정",
-      "description": "공유한 페이지를 읽습니다.",
-      "kind": "oauth_access_token",
-      "required": true,
-      "oauth_provider": "notion",
-      "allow_multiple": true
-    }
-  ],
-  "connectors": [
-    {
-      "id": "notion_cloud",
-      "kind": "oauth",
-      "label": "Notion Cloud",
-      "description": "Notion 공식 OAuth 연결",
-      "credential_id": "notion_account",
-      "cloud_connection_id": "notion"
-    }
-  ]
-}
-```
-
-조직 Secret:
-
-```json
-{
-  "cloud_project_id": "00000000-0000-4000-8000-000000000000",
-  "required_secrets": [
-    {
-      "id": "EXAMPLE_API_KEY",
-      "label": "Example API key",
-      "description": "서버 간 API 호출에 사용합니다.",
-      "required": true
-    }
-  ],
-  "connectors": [
-    {
-      "id": "example_api",
-      "kind": "api_key",
-      "label": "Example API",
-      "description": "조직 API 연결",
-      "cloud_secret_id": "EXAMPLE_API_KEY"
-    }
-  ]
-}
-```
-
-`cloud_project_id`는 Developer Project에 연결할 때 발급된 실제 UUID를 사용합니다.
-
-## Developer Platform 설정
-
-1. 조직을 선택하고 Plugin Project를 엽니다.
-2. Secrets에서 manifest의 `required_secrets.id`와 같은 ID를 등록합니다.
-3. Connections에서 `cloud_connection_id`와 같은 provider 설정을 만듭니다.
-4. OAuth authorize URL, token URL, client ID, client secret, redirect URI를 공급자 문서와 맞춥니다.
-5. 필요한 header/content type과 PKCE 지원 여부를 명시합니다.
-6. source를 sync하고 새 Deployment를 build합니다.
-
-Secret 값은 저장 후 다시 평문으로 표시되거나 source ZIP, MCP 응답, build log에 포함되면 안 됩니다.
-변경은 새 값으로 덮어쓰고 필요한 경우 provider에서 기존 값을 폐기합니다.
-
-## 사용자 연결 흐름
-
-```text
-설치·활성화
-  → 필요한 Connection 없음
-  → 설정에서 “계정 연결”
-  → Host가 state와 redirect를 생성
-  → provider 승인
-  → Host callback에서 state 검증과 token 교환
-  → 암호화 저장
-  → default Instance에 Connection 연결
-```
-
-`allow_multiple: true`이면 같은 default Instance 안에 여러 Connection을 만들고 사용자가 표시 이름으로
-선택합니다. 같은 package root Instance를 복제해 계정을 추가하지 않습니다.
-
-OAuth state와 redirect URI는 필수입니다. PKCE는 공급자 호환 설정에 따라 사용하지만 state 검증을
-대체하지 않습니다. callback이 성공하기 전에 연결 완료로 표시하지 않습니다.
-
-## 실행과 갱신
-
-Capability는 `connector_id`만 참조합니다. Host는 선택된 Connection의 token을 요청 직전에 주입하고
-응답과 로그에서 제거합니다. credential 거부가 명확하고 provider가 refresh를 지원하면 한 번 갱신한
-뒤 전체 요청을 재시도합니다. 반복 실패는 “다시 연결” 상태로 전환합니다.
-
-Connection 상태를 구분합니다.
-
-- `ready`: 필요한 credential과 runtime이 준비됨
-- `not_configured`: 필수 Connection/Secret이 없음
-- `unavailable`: provider, 암호화, dependency, network runtime을 사용할 수 없음
-- 만료·거부: 사용자 재연결 필요
-
-## 연결 해제와 삭제
-
-Instance Connection 삭제는 해당 연결 row의 encrypted credential, 진행 중 OAuth state, 관련 pending
-Host action을 로컬에서 정리하고 generation을 갱신합니다. 이 API를 provider token revoke가
-완료됐다는 증거로 사용하지 않습니다.
-
-기존 default credential 해제 API는 provider에 revocation endpoint가 있으면 먼저 revoke하고 성공한
-경우에만 local credential을 삭제합니다. provider 오류가 나면 암호화된 credential을 유지하고 오류를
-반환하므로 사용자가 다시 시도할 수 있습니다. Plugin 전체 삭제는 remote revoke를 가능한 범위에서
-시도한 뒤 `data_policy: retain`이어도 local credential과 OAuth state를 보존하지 않습니다.
-
-## 운영 점검
-
-- authorize 요청마다 새로운 state가 생성되는가
-- redirect URI가 등록값과 정확히 일치하는가
-- token URL과 content type이 provider 요구와 맞는가
-- client secret과 access token이 로그·MCP·artifact에 없는가
-- 여러 Connection의 token과 표시 이름이 섞이지 않는가
-- token 만료 후 한 번 갱신하고, 실패 시 재연결을 안내하는가
-- Connection 삭제 후 해당 연결의 실행이 즉시 차단되고 local credential이 제거되는가
-- provider revoke가 제품 요구사항이면 공급자 console에서도 token 폐기를 별도로 확인했는가
-- 플러그인 삭제 후 local credential과 OAuth state가 남지 않는가
-
-Notion의 실제 구성은 [Notion 플러그인](examples-notion.md)을 참고하세요.