diff --git a/agent-ops/rules/common/rules-agent-ui.md b/agent-ops/rules/common/rules-agent-ui.md index 179e722..a875401 100644 --- a/agent-ops/rules/common/rules-agent-ui.md +++ b/agent-ops/rules/common/rules-agent-ui.md @@ -39,7 +39,7 @@ agent-ui/ index.md views/ / - index.md + index.md # visual source가 있을 때만 생성 wire.excalidraw # 선택: 1차 visual source 후보 ``` @@ -47,7 +47,8 @@ agent-ui/ - `agent-ui/definition/**`은 현재 UI 정의의 source of truth다. - `agent-ui/frame/**`은 와이어프레임과 visual source를 연결하는 보조 자료다. -- `.excalidraw` 파일만으로 현재 UI 기준을 확정하지 않는다. 반드시 대응되는 `frame/views//index.md`가 있어야 한다. +- visual source가 없는 view는 `frame/views//`를 만들지 않는다. view 문서의 `frame`은 `null`로 둔다. +- `.excalidraw` 파일만으로 현재 UI 기준을 확정하지 않는다. visual source가 있으면 반드시 대응되는 `frame/views//index.md`가 있어야 한다. - `frame/views//index.md`는 대응되는 `definition/views//index.md`를 가리켜야 한다. - 화면 의도, 상태, 액션, 정보 우선순위는 definition에 둔다. - 배치, 밀도, 시각적 영역 관계는 frame에 둔다. @@ -62,12 +63,14 @@ agent-ui/ - definition-index 문서는 `surface_type`, `source_evidence`를 둘 수 있다. - view 문서는 `view_id`, `status`, `frame`, `source_evidence`를 둔다. - component 문서는 `component_id`, `status`, `source_evidence`를 둔다. -- frame-view 문서는 `view_id`, `definition`, `visual_source`, `regions`를 둔다. +- view 문서의 `frame`은 frame-view 문서가 있으면 경로, 없으면 `null`로 둔다. +- frame-view 문서는 visual source가 있을 때만 만들며 `view_id`, `definition`, `visual_source`, `regions`를 둔다. - `status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나다. - `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다. - `source_evidence.type`은 `code`, `docs`, `user` 중 하나다. - 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다. -- `visual_source`가 아직 없으면 `null`을 사용한다. 없는 `wire.excalidraw`를 기본 근거처럼 쓰지 않는다. +- view에 visual source가 없으면 view 문서의 `frame`을 `null`로 두고 frame-view 문서를 만들지 않는다. +- frame-view를 만들 때 `visual_source`는 실제 존재하는 visual source 경로여야 한다. 없는 `wire.excalidraw`를 기본 근거처럼 쓰지 않는다. - `implemented`는 존재하는 `code` evidence path가 있을 때만 사용한다. - `planned`는 문서 근거만 있을 때, `assumed`는 사용자 명시 입력만 있을 때, `unknown`은 근거나 판단이 부족할 때 사용한다. - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`는 같은 기준을 말해야 한다. @@ -86,9 +89,9 @@ agent-ui/ - region id는 `.` 형식을 사용한다. - 하위 region은 `..` 형식을 사용할 수 있다. - component id는 `definition/components/` 아래 경로에서 `index.md`를 제외한 path id로 본다. 예: `data-table`, `data-table/job-list`. -- view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다. +- frame-view가 있으면 view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다. - view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다. -- frame-view frontmatter의 `regions`와 view 본문의 region id는 같은 집합이어야 한다. 단, 차이가 제품 판단을 요구하면 USER_REVIEW로 남긴다. +- frame-view가 있으면 frame-view frontmatter의 `regions`와 view 본문의 region id는 같은 집합이어야 한다. 단, 차이가 제품 판단을 요구하면 USER_REVIEW로 남긴다. ## Archive 접근 diff --git a/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md b/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md index a84717f..bf02571 100644 --- a/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md @@ -45,7 +45,7 @@ source_evidence: ## Sync Rules -- view region id와 frame region id는 동일해야 한다. +- frame-view가 있으면 view region id와 frame region id는 동일해야 한다. - view에서 참조한 component id는 `components/` 아래에 정의되어야 한다. - frame은 definition을 대체하지 않는다. - `implemented`, `planned`, `assumed`, `unknown` 상태를 섞어 쓰지 않는다. diff --git a/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md b/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md index f6363aa..88b72e9 100644 --- a/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md @@ -7,15 +7,16 @@ frames: [] ## Purpose -이 디렉터리는 view별 wireframe, visual source, definition 연결 정보를 보관한다. +이 디렉터리는 visual source가 있는 view의 wireframe과 definition 연결 정보를 보관한다. ## Frame Sources -- `views//index.md`: view별 frame 연결 문서 +- `views//index.md`: visual source가 있는 view의 frame 연결 문서 - `views//wire.excalidraw`: 선택 visual source ## Rules - frame은 definition을 대체하지 않는다. - visual source가 있으면 대응되는 frame index에 기록한다. -- frame region id는 definition region id와 동일해야 한다. +- visual source가 없으면 `views//`를 만들지 않는다. +- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다. diff --git a/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md b/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md index b907b76..ad95a1c 100644 --- a/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md @@ -2,7 +2,7 @@ ui_doc_type: frame-view view_id: definition: ../../../definition/views//index.md -visual_source: null +visual_source: regions: - . --- @@ -13,7 +13,7 @@ Definition: - `../../../definition/views//index.md` Visual Source: -- 없음 +- `` ## Frame Intent diff --git a/agent-ops/skills/common/_templates/agent-ui/readme-template.md b/agent-ops/skills/common/_templates/agent-ui/readme-template.md index 5629284..95bd50d 100644 --- a/agent-ops/skills/common/_templates/agent-ui/readme-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/readme-template.md @@ -15,13 +15,13 @@ surface_type: ops-dev ## 구조 - `definition/`: 현재 UI 정의 source of truth -- `frame/`: view별 wireframe과 visual source 연결 +- `frame/`: visual source가 있는 view의 wireframe 연결 - `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문 - `archive/user-review/`: 해결된 사용자 리뷰 로그 ## 기본 규칙 - 현재 기준은 `definition/**`에 둔다. -- visual wireframe은 `frame/**`에 둔다. +- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다. - `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다. - `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다. diff --git a/agent-ops/skills/common/_templates/agent-ui/view-index-template.md b/agent-ops/skills/common/_templates/agent-ui/view-index-template.md index a5a1ccb..3a80499 100644 --- a/agent-ops/skills/common/_templates/agent-ui/view-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/view-index-template.md @@ -2,7 +2,7 @@ ui_doc_type: view view_id: status: -frame: ../../../frame/views//index.md +frame: null source_evidence: - type: code path: null @@ -22,7 +22,7 @@ regions: View ID: `` Frame: -- `../../../frame/views//index.md` +- 없음 Status: `` diff --git a/agent-ops/skills/common/create-agent-ui/SKILL.md b/agent-ops/skills/common/create-agent-ui/SKILL.md index 0e9ed73..392defb 100644 --- a/agent-ops/skills/common/create-agent-ui/SKILL.md +++ b/agent-ops/skills/common/create-agent-ui/SKILL.md @@ -78,15 +78,16 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - `blank`에서는 명시 `views`가 있을 때만 view 후보를 만든다. - 각 view 후보마다 다음 문서를 만든다. - `agent-ui/definition/views//index.md` - - `agent-ui/frame/views//index.md` - view 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다. - 코드 근거가 있으면 `status: implemented` - 문서 근거만 있으면 `status: planned` - 명시 입력만 있고 근거가 부족하면 `status: assumed` - 판단 불가하면 `status: unknown`과 USER_REVIEW 항목을 남긴다. - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다. + - visual source가 없는 초기 view 문서의 frontmatter `frame`은 `null`로 둔다. - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 같은 기준을 말하게 작성한다. - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다. + - `.excalidraw` 또는 다른 visual source를 만들거나 연결할 때만 `agent-ui/frame/views//index.md`를 만든다. - `.excalidraw`를 만들거나 연결하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다. - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다. @@ -123,6 +124,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - [ ] view/component는 folder-first + `index.md` 구조를 사용하는가 - [ ] 생성한 view/component에 `Source Evidence`와 `Status`가 있는가 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가 +- [ ] visual source가 없는 view에 빈 `frame/views//index.md`를 만들지 않았는가 - [ ] 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가 - [ ] 같은 레벨에 `.md`와 `/`가 함께 생기지 않았는가 - [ ] archive 본문 파일을 불필요하게 생성하지 않았는가 diff --git a/agent-ops/skills/common/update-agent-ui/SKILL.md b/agent-ops/skills/common/update-agent-ui/SKILL.md index 7df7325..f9cfd03 100644 --- a/agent-ops/skills/common/update-agent-ui/SKILL.md +++ b/agent-ops/skills/common/update-agent-ui/SKILL.md @@ -10,6 +10,7 @@ description: 기존 agent-ui의 view, component, frame, wireframe 연결, source 기존 `agent-ui/`의 UI 정의를 갱신한다. view, component, frame index, Excalidraw visual source 연결, source evidence, status를 현재 기준에 맞게 수정하고, 오래된 기준은 필요한 경우 archive log로 분리한다. +frame-view는 visual source가 있을 때만 활성 문서로 둔다. ## 언제 호출할지 @@ -42,7 +43,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, ## 실행 절차 1. **대상 분류** - - `view-id`가 있으면 view 정의와 대응 frame 문서를 대상으로 삼는다. + - `view-id`가 있으면 view 정의를 대상으로 삼고, frame 문서가 있거나 `frame-source`가 입력된 경우에만 frame 문서를 대상으로 삼는다. - `component-id`가 있으면 component 정의를 대상으로 삼는다. - `frame-source`가 있으면 대응 `frame/views//index.md`에 visual source를 연결한다. - 대상이 모호하면 추정으로 새 문서를 만들지 않고 `agent-ui/USER_REVIEW.md`에 결정 항목을 남긴다. @@ -60,13 +61,14 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, - 오래된 결정이 현재 기준을 흐리면 대응되는 `definition/archive/**.log`로 이동하거나 추가한다. 3. **frame 갱신** - - 대응되는 `frame/views//index.md`가 없으면 템플릿으로 만든다. + - `frame-source`가 있고 대응되는 `frame/views//index.md`가 없으면 템플릿으로 만든다. - visual source가 있으면 frontmatter `visual_source`와 본문 `Visual Source`에 함께 기록한다. - - visual source가 없으면 frontmatter `visual_source`는 `null`로 둔다. + - visual source가 없으면 새 frame-view 문서를 만들지 않는다. + - 기존 frame-view 문서의 visual source가 제거되고 더 이상 연결할 visual source가 없으면 frame-view 삭제 후보로 보고한다. 판단이 명확하면 삭제하고 view 문서의 `frame`을 `null`로 둔다. - Excalidraw visual source의 기본 후보 파일명은 `wire.excalidraw`다. - `.excalidraw`를 만들거나 수정하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다. - - frame의 required region id는 view definition의 region id와 맞춘다. - - 정의에 없는 region이 frame에 필요하면 바로 확정하지 않고 open question 또는 USER_REVIEW로 분리한다. + - frame-view가 있으면 required region id는 view definition의 region id와 맞춘다. + - 정의에 없는 region이 frame-view에 필요하면 바로 확정하지 않고 open question 또는 USER_REVIEW로 분리한다. 4. **USER_REVIEW 처리** - agent가 확정할 수 없는 화면 의도, region 추가/삭제, component 신규 생성 여부, page/drawer/split 선택은 `agent-ui/USER_REVIEW.md`에 남긴다. @@ -87,9 +89,10 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, - [ ] 새로 만들거나 수정한 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가 - [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가 -- [ ] view region id와 frame region id가 충돌하지 않는가 +- [ ] frame-view가 있으면 view region id와 frame region id가 충돌하지 않는가 - [ ] view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가 - [ ] visual source가 있으면 대응 frame index에 기록되었는가 +- [ ] visual source가 없는데 빈 frame-view 문서만 남아 있지 않은가 - [ ] 현재 기준이 archive에만 남지 않았는가 - [ ] 확정할 수 없는 UI 결정이 임의로 확정되지 않았는가 - 검증 실패 시: 자동 보정 가능한 것은 보완하고, 판단이 필요한 것은 `agent-ui/USER_REVIEW.md`에 남긴다. @@ -118,4 +121,5 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, - 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다. - view/component id를 명시적 요청 없이 바꾸지 않는다. - `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다. +- visual source 없이 빈 frame-view 문서를 만들지 않는다. - agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다. diff --git a/agent-ops/skills/common/validate-agent-ui/SKILL.md b/agent-ops/skills/common/validate-agent-ui/SKILL.md index bd3d84f..a7f10e9 100644 --- a/agent-ops/skills/common/validate-agent-ui/SKILL.md +++ b/agent-ops/skills/common/validate-agent-ui/SKILL.md @@ -41,13 +41,14 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu 1. **인벤토리 작성** - `definition/views/**/index.md`에서 view 목록을 만든다. - `definition/components/**/index.md`에서 component 목록을 만든다. - - `frame/views/**/index.md`에서 frame 목록을 만든다. + - `frame/views/**/index.md`에서 frame 목록을 만든다. frame이 없는 view는 visual source가 없는 정상 상태로 본다. - 활성 Markdown 문서의 frontmatter에서 `ui_doc_type`, id, status, source_evidence, regions를 수집한다. - 같은 레벨의 `.md`와 `/` 혼재 여부를 확인한다. 2. **구조 검증과 자동 보정** - 필수 루트 문서가 없고 `repair=true`이면 템플릿으로 생성한다. - - view/component/frame 디렉터리에 `index.md`가 없고 의도가 명확하면 템플릿으로 생성한다. + - view/component 디렉터리에 `index.md`가 없고 의도가 명확하면 템플릿으로 생성한다. + - frame 디렉터리는 visual source가 있을 때만 `index.md` 생성 대상으로 삼는다. - `.excalidraw` 파일이 하나 있고 frame index의 visual source가 비어 있으면 해당 파일을 등록한다. - archive/user-review 디렉터리가 없고 필요하면 생성한다. - `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다. @@ -72,9 +73,11 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - 새 component로 만들지 기존 component로 바꿀지 판단이 필요하면 USER_REVIEW로 남긴다. 4. **frame 정합성 검사** - - view가 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다. + - view가 있는데 대응 frame index가 없어도 visual source가 없으면 정상으로 본다. + - visual source 파일이 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다. + - frame index가 있는데 `visual_source: null`이고 해당 view 아래 visual source 파일도 없으면 `repair=true`일 때 빈 frame index 삭제 후보로 본다. - frame index가 가리키는 definition 경로가 실제 존재하는지 확인한다. - - `visual_source`가 `null`이면 visual source 없음으로 본다. + - `visual_source`가 `null`이면 legacy/empty frame 후보로 보고 visual source 파일 존재 여부를 함께 확인한다. - `visual_source`가 값이면 해당 파일이 실제 존재하는지 확인한다. - `visual_source`가 `.excalidraw`이면 JSON으로 읽고 `elements`의 text label 또는 `customData.region_id`에서 region id 후보를 수집한다. - Excalidraw region id 후보가 있으면 frame required region, view definition region과 비교한다. @@ -82,8 +85,8 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - Excalidraw에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동 수정하지 않고 USER_REVIEW로 남긴다. - Excalidraw가 JSON으로 파싱되지 않으면 visual source 손상 또는 형식 불일치로 보고한다. - frame required region과 view definition region을 비교한다. - - definition에 있는 region이 frame index에만 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다. - - frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다. + - visual source가 있는 frame index에서 definition region이 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다. + - 기존 frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다. - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다. 5. **구현 정합성 검사** @@ -116,7 +119,7 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - 누락된 필수 디렉터리와 index 문서 생성 - 명확한 단일 후보 visual source 등록 - 명확한 단일 후보 상대 링크 보정 -- definition에 이미 있는 region의 frame index 누락 보완 +- visual source가 있는 frame index의 region 누락 보완 - 빈 archive/user-review 디렉터리 생성 - 템플릿 필수 섹션과 frontmatter 누락 보완. `ui_doc_type`, `Source Evidence`, `Status` 누락 포함 - 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다. @@ -125,8 +128,8 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu ## USER_REVIEW 대상 -- 정의에는 없는 region이 frame에 있고 추가/삭제 의도 판단이 필요한 경우 -- frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우 +- 정의에는 없는 region이 기존 frame-view에 있고 추가/삭제 의도 판단이 필요한 경우 +- frame-view가 있는데 frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우 - component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우 - 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우 - 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우 @@ -142,6 +145,7 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - [ ] 명시된 code evidence 경로가 깨진 `implemented`가 남아 있지 않은가 - [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보가 agent-ui에 반영되었거나 USER_REVIEW에 남았는가 - [ ] view/component/frame 참조가 끊기지 않는가 +- [ ] visual source가 없는 view는 frame 참조가 `null`이거나 비어 있는 frame-view가 없는가 - [ ] 자동 수정한 파일 목록이 보고되는가 - [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가 - [ ] archive 본문을 일반 검증에서 읽지 않았는가 diff --git a/agent-ui/README.md b/agent-ui/README.md new file mode 100644 index 0000000..0f3b568 --- /dev/null +++ b/agent-ui/README.md @@ -0,0 +1,29 @@ +--- +ui_doc_type: readme +surface_type: ops-dev +--- + +# agent-ui + +이 디렉터리는 AI agent와 사람이 OTO Control Plane UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다. + +## 대상 + +- 1차 대상: ops/dev UI +- 현재 표면: Flutter OTO Console client +- 확장 후보: product UI 레이어가 필요해지면 brand, content, assets, tokens, motion 정의를 이 구조 위에 추가한다. + +## 구조 + +- `definition/`: 현재 UI 정의 source of truth +- `frame/`: visual source가 있는 view의 wireframe 연결 +- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문이 생길 때만 생성 +- `archive/user-review/`: 해결된 사용자 리뷰 로그 + +## 기본 규칙 + +- 현재 기준은 `definition/**`에 둔다. +- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다. +- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다. +- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다. +- 구현 코드에서 확인된 항목은 `implemented`, 문서 계획에서 온 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 표시한다. diff --git a/agent-ui/archive/user-review/.gitkeep b/agent-ui/archive/user-review/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/agent-ui/archive/user-review/.gitkeep @@ -0,0 +1 @@ + diff --git a/agent-ui/definition/archive/components/.gitkeep b/agent-ui/definition/archive/components/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/agent-ui/definition/archive/components/.gitkeep @@ -0,0 +1 @@ + diff --git a/agent-ui/definition/archive/views/.gitkeep b/agent-ui/definition/archive/views/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/agent-ui/definition/archive/views/.gitkeep @@ -0,0 +1 @@ + diff --git a/agent-ui/definition/components/action-feedback/index.md b/agent-ui/definition/components/action-feedback/index.md new file mode 100644 index 0000000..89b0c58 --- /dev/null +++ b/agent-ui/definition/components/action-feedback/index.md @@ -0,0 +1,73 @@ +--- +ui_doc_type: component +component_id: action-feedback +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart + notes: "runner self-update result feedback" + - type: code + path: packages/flutter/oto_console/lib/src/oto_jobs_surface.dart + notes: "job create result feedback" + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "execution action result feedback" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoActionViewState 상태 모델" +--- + +# Action Feedback + +Component ID: `action-feedback` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | runner self-update result feedback | +| code | `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart` | job create result feedback | +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | execution action result feedback | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoActionViewState` | + +## Purpose + +write action 결과를 success, deferred, failed 상태로 짧게 표시한다. + +## Used By + +- `runners`: `runners.action-feedback` +- `pipelines`: `pipelines.action-feedback` +- `executions`: `executions.action-feedback` + +## Anatomy + +- tinted result container +- message text +- success/failure color +- deferred prefix where available + +## Variants + +- success +- deferred +- failed + +## States + +- succeeded +- deferred +- failed +- hidden when idle/submitting + +## Rules + +- 민감 error payload를 그대로 노출하지 않아야 한다. +- 권한 실패가 추가되면 forbidden/unauthorized 문구와 audit metadata 노출 기준을 SDD와 맞춘다. + +## Decision History + +- 2026-06-24: write action 결과 표시를 `action-feedback` component로 정의했다. + diff --git a/agent-ui/definition/components/agent-chat-panel/index.md b/agent-ui/definition/components/agent-chat-panel/index.md new file mode 100644 index 0000000..a83054e --- /dev/null +++ b/agent-ui/definition/components/agent-chat-panel/index.md @@ -0,0 +1,66 @@ +--- +ui_doc_type: component +component_id: agent-chat-panel +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_agent_panel.dart + notes: "OtoAgentPanel, AgentShell mount" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoCapabilityPack, OtoCapability" + - type: docs + path: apps/client/README.md + notes: "oto_console embeddable widget" +--- + +# Agent Chat Panel + +Component ID: `agent-chat-panel` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_agent_panel.dart` | `OtoAgentPanel`, `AgentShell` mount | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoCapabilityPack`, `OtoCapability` | +| docs | `apps/client/README.md` | embeddable widget 기준 | + +## Purpose + +OTO capabilities를 안내하는 agent-shell 기반 대화 표면을 제공한다. + +## Used By + +- `agent`: `agent.conversation`, `agent.capabilities`, `agent.input` + +## Anatomy + +- assistant intro message +- optional registered capabilities list +- prompt input +- submit callback + +## Variants + +- no capabilities: intro message only +- capabilities-present: registered capabilities summary 포함 + +## States + +- default +- empty-capabilities +- busy: 현재 구현은 false 고정 +- error: 없음 + +## Rules + +- capability name/description은 host가 넘긴 `OtoCapabilityPack`을 기준으로 표시한다. +- prompt placeholder는 OTO build 문맥을 유지한다. + +## Decision History + +- 2026-06-24: OTO agent panel을 `agent-chat-panel` component로 정의했다. + diff --git a/agent-ui/definition/components/artifact-list/index.md b/agent-ui/definition/components/artifact-list/index.md new file mode 100644 index 0000000..61ff700 --- /dev/null +++ b/agent-ui/definition/components/artifact-list/index.md @@ -0,0 +1,72 @@ +--- +ui_doc_type: component +component_id: artifact-list +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart + notes: "Artifacts tab list 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "execution detail artifact preview 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoArtifactViewModel" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "artifact 내용/full path 감사 복제 금지 기준" +--- + +# Artifact List + +Component ID: `artifact-list` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart` | Artifacts tab list 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | execution detail artifact preview 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoArtifactViewModel` | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | artifact 내용/full path 감사 복제 금지 기준 | + +## Purpose + +artifact name과 path를 row 목록으로 보여준다. + +## Used By + +- `artifacts`: `artifacts.artifact-list` +- `executions`: `executions.artifacts-preview` + +## Anatomy + +- file icon +- artifact name +- artifact path +- compact card/list row + +## Variants + +- full tab row +- execution detail compact card + +## States + +- default +- empty +- loading +- error +- truncated + +## Rules + +- artifact path는 길면 ellipsis 처리한다. +- audit UI에서는 artifact content나 민감한 full path를 복제 노출하지 않는다. + +## Decision History + +- 2026-06-24: artifact tab과 execution detail preview를 `artifact-list` component로 묶었다. + diff --git a/agent-ui/definition/components/audit-action-summary/index.md b/agent-ui/definition/components/audit-action-summary/index.md new file mode 100644 index 0000000..84487bd --- /dev/null +++ b/agent-ui/definition/components/audit-action-summary/index.md @@ -0,0 +1,74 @@ +--- +ui_doc_type: component +component_id: audit-action-summary +status: planned +source_evidence: + - type: docs + path: agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md + notes: "audit-scope Task가 action metadata와 UI 노출/마스킹 경계를 요구" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "D02, D03, S04가 actor/action/target/outcome/timestamp/reason 노출과 민감 정보 비노출 기준을 정의" + - type: user + path: null + notes: "agent-ui 재검토 중 SDD 기반 planned component로 보강" +--- + +# Audit Action Summary + +Component ID: `audit-action-summary` + +Status: `planned` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| docs | `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md` | `audit-scope` Task가 action metadata와 UI 노출/마스킹 경계를 요구 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | D02, D03, S04가 audit metadata 노출과 민감 정보 비노출 기준을 정의 | +| user | 없음 | agent-ui 재검토 중 SDD 기반 planned component로 보강 | + +## Purpose + +Control Plane write action 결과를 감사 관점에서 확인할 수 있도록 display-safe metadata만 요약한다. + +## Used By + +- `runners`: self-update action metadata 후보 +- `pipelines`: create job action metadata 후보 +- `executions`: cancel/report/log/artifact action metadata 후보 + +## Anatomy + +- action +- actor reference +- target id +- outcome +- timestamp +- optional reason + +## Variants + +- accepted +- rejected +- deferred +- failed + +## States + +- planned +- populated +- empty +- masked +- error + +## Rules + +- auth token, enrollment token, credential 원문, private release URL credential을 표시하지 않는다. +- raw log line, artifact 내용, 민감 error payload를 audit summary에 복제하지 않는다. +- durable audit persistence가 필요하면 후속 Milestone 또는 SDD로 분리한다. + +## Decision History + +- 2026-06-24: 활성 보안/감사 SDD를 반영해 planned component로 추가했다. + diff --git a/agent-ui/definition/components/auth-token-reference/index.md b/agent-ui/definition/components/auth-token-reference/index.md new file mode 100644 index 0000000..d7be519 --- /dev/null +++ b/agent-ui/definition/components/auth-token-reference/index.md @@ -0,0 +1,65 @@ +--- +ui_doc_type: component +component_id: auth-token-reference +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_overview.dart + notes: "Active Auth Token Reference endpoint tile" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoConsoleConfig.authTokenReference" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "token 원문이 아닌 표시 가능한 reference만 UI에 노출" +--- + +# Auth Token Reference + +Component ID: `auth-token-reference` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_overview.dart` | Active Auth Token Reference 표시 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoConsoleConfig.authTokenReference` | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | token reference 노출 기준 | + +## Purpose + +현재 runtime이 사용하는 인증 토큰을 원문이 아닌 표시 가능한 reference로만 보여준다. + +## Used By + +- `overview`: `overview.authentication` + +## Anatomy + +- security section header +- key icon tile +- token reference value or `None` + +## Variants + +- present: reference string 표시 +- absent: `None` 표시 + +## States + +- default +- absent +- truncated +- error: 없음 + +## Rules + +- token 원문, credential, private URL credential을 표시하지 않는다. +- 값이 길면 ellipsis 처리한다. + +## Decision History + +- 2026-06-24: SDD의 노출 경계를 반영해 `auth-token-reference` component로 정의했다. + diff --git a/agent-ui/definition/components/authorization-state/index.md b/agent-ui/definition/components/authorization-state/index.md new file mode 100644 index 0000000..d1cd579 --- /dev/null +++ b/agent-ui/definition/components/authorization-state/index.md @@ -0,0 +1,72 @@ +--- +ui_doc_type: component +component_id: authorization-state +status: planned +source_evidence: + - type: docs + path: agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md + notes: "auth-scope Task가 operator/admin 단일 역할과 허용/거부, disabled/error 상태 구현을 요구" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "D01과 S03이 최소 인증 모델, role, unauthorized/forbidden UX 기준을 정의" + - type: user + path: null + notes: "agent-ui 재검토 중 SDD 기반 planned component로 보강" +--- + +# Authorization State + +Component ID: `authorization-state` + +Status: `planned` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| docs | `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md` | `auth-scope` Task가 operator/admin 단일 역할과 허용/거부, disabled/error 상태 구현을 요구 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | D01과 S03이 최소 인증 모델, role, unauthorized/forbidden UX 기준을 정의 | +| user | 없음 | agent-ui 재검토 중 SDD 기반 planned component로 보강 | + +## Purpose + +write action 표면에서 operator/admin 권한 허용, 거부, disabled, error 상태를 일관되게 표현한다. + +## Used By + +- `runners`: self-update action 권한 상태 후보 +- `pipelines`: create job action 권한 상태 후보 +- `executions`: cancel/report/log/artifact action 권한 상태 후보 + +## Anatomy + +- allowed/disabled affordance +- unauthorized/forbidden message +- optional token reference context +- action guard reason + +## Variants + +- allowed: action submit 가능 +- disabled: 권한 또는 입력 조건 때문에 submit 불가 +- unauthorized: 인증 reference 부재 또는 무효 +- forbidden: operator/admin 기준 미충족 + +## States + +- allowed +- disabled +- unauthorized +- forbidden +- error + +## Rules + +- production identity provider를 전제하지 않는다. +- token 원문을 표시하지 않고 `auth-token-reference`의 display-safe reference만 연결한다. +- 권한 실패 message는 민감 payload를 그대로 노출하지 않는다. + +## Decision History + +- 2026-06-24: 활성 보안/감사 SDD를 반영해 planned component로 추가했다. + diff --git a/agent-ui/definition/components/connection-status-grid/index.md b/agent-ui/definition/components/connection-status-grid/index.md new file mode 100644 index 0000000..6308151 --- /dev/null +++ b/agent-ui/definition/components/connection-status-grid/index.md @@ -0,0 +1,67 @@ +--- +ui_doc_type: component +component_id: connection-status-grid +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_overview.dart + notes: "_ConnectionGrid, _EndpointStatusTile 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoCoreConnectionSnapshot, OtoCoreEndpointStatus 상태 모델" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Connection Status Grid + +Component ID: `connection-status-grid` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_overview.dart` | `_ConnectionGrid`, `_EndpointStatusTile` 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | connection snapshot 상태 모델 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Core health/readiness endpoint 결과를 함께 비교해서 online/degraded/offline 판단을 돕는다. + +## Used By + +- `overview`: `overview.connection-status` + +## Anatomy + +- health status tile +- readiness status tile +- status label +- HTTP status/path detail + +## Variants + +- wide: two-column row +- narrow: stacked column + +## States + +- checking +- online +- degraded +- offline +- error + +## Rules + +- health와 readiness 중 하나만 OK이면 degraded로 해석한다. +- status code가 없으면 path만 표시한다. + +## Decision History + +- 2026-06-24: overview connection grid를 component로 정의했다. + diff --git a/agent-ui/definition/components/console-rail/index.md b/agent-ui/definition/components/console-rail/index.md new file mode 100644 index 0000000..feb1a6a --- /dev/null +++ b/agent-ui/definition/components/console-rail/index.md @@ -0,0 +1,72 @@ +--- +ui_doc_type: component +component_id: console-rail +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "_OtoConsoleRail, _RailButton 구현" + - type: docs + path: apps/client/README.md + notes: "oto_console embeddable UI surface" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Console Rail + +Component ID: `console-rail` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | `_OtoConsoleRail`, `_RailButton` 구현 | +| docs | `apps/client/README.md` | embeddable console surface | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +콘솔 section 사이를 빠르게 이동하는 고정 rail navigation을 제공한다. + +## Used By + +- `overview`: shell navigation +- `runners`: shell navigation +- `pipelines`: shell navigation +- `executions`: shell navigation +- `artifacts`: shell navigation +- `agent`: shell navigation +- `settings`: shell navigation + +## Anatomy + +- icon button +- tooltip +- selected visual state +- top main section group +- bottom agent/settings group + +## Variants + +- default: 60px rail width, 56x48 button hit area +- selected: primary color icon and tinted background + +## States + +- default +- selected +- hover/focus via Flutter button semantics +- disabled: 없음 + +## Rules + +- navigation destination은 `OtoConsoleSection` enum과 일치해야 한다. +- section 추가 시 rail button, enum, view definition을 함께 갱신하고, visual source가 있으면 frame-view definition도 함께 갱신한다. + +## Decision History + +- 2026-06-24: shell rail을 `console-rail` component로 정의했다. diff --git a/agent-ui/definition/components/console-shell/index.md b/agent-ui/definition/components/console-shell/index.md new file mode 100644 index 0000000..48d5f0d --- /dev/null +++ b/agent-ui/definition/components/console-shell/index.md @@ -0,0 +1,73 @@ +--- +ui_doc_type: component +component_id: console-shell +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "OtoConsoleShell Scaffold, rail, selected section content 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "OtoClientApp이 OtoConsoleShell을 host MaterialApp home으로 mount" + - type: docs + path: apps/client/README.md + notes: "oto_console package의 embeddable shell 기준" +--- + +# Console Shell + +Component ID: `console-shell` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | `OtoConsoleShell` Scaffold, rail, selected section content 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | host `MaterialApp`이 `OtoConsoleShell`을 mount | +| docs | `apps/client/README.md` | embeddable shell 기준 | + +## Purpose + +Control Plane 콘솔의 전체 layout shell을 제공하고, rail navigation과 선택된 section content를 연결한다. + +## Used By + +- `overview`: shell content area +- `runners`: shell content area +- `pipelines`: shell content area +- `executions`: shell content area +- `artifacts`: shell content area +- `agent`: shell content area +- `settings`: shell content area + +## Anatomy + +- `Scaffold` +- `SafeArea` +- `console-rail` +- selected section content area +- optional fallback `section-surface` + +## Variants + +- default: host가 전용 surface를 모두 넘긴 상태 +- fallback: 특정 section widget이 없으면 `section-surface`를 표시 + +## States + +- default +- selected-section +- fallback-section +- navigation-callback + +## Rules + +- section enum, rail button, view definition은 같은 section 집합을 말해야 한다. +- shell은 view source of truth가 아니라 view를 담는 container component다. + +## Decision History + +- 2026-06-24: 구현 후보 재검토 중 `OtoConsoleShell`을 별도 shell component로 보강했다. + diff --git a/agent-ui/definition/components/endpoint-tile/index.md b/agent-ui/definition/components/endpoint-tile/index.md new file mode 100644 index 0000000..c70c8b7 --- /dev/null +++ b/agent-ui/definition/components/endpoint-tile/index.md @@ -0,0 +1,67 @@ +--- +ui_doc_type: component +component_id: endpoint-tile +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_overview.dart + notes: "_EndpointTile 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "_SectionDetailTile fallback detail 구현" + - type: docs + path: apps/client/README.md + notes: "server URL, preview port, browser policy context" +--- + +# Endpoint Tile + +Component ID: `endpoint-tile` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_overview.dart` | `_EndpointTile` 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | `_SectionDetailTile` fallback detail 구현 | +| docs | `apps/client/README.md` | server URL, preview port, browser policy context | + +## Purpose + +endpoint, policy, 설정 값처럼 운영자가 복사하거나 비교해야 하는 짧은 key/value 정보를 표시한다. + +## Used By + +- `overview`: `overview.endpoints` +- `settings`: `settings.endpoint-details` + +## Anatomy + +- leading icon +- title +- value +- bordered surface + +## Variants + +- overview endpoint tile +- settings detail tile + +## States + +- default +- value-empty +- truncated +- error: 없음 + +## Rules + +- value는 한 줄 ellipsis를 기본으로 한다. +- credential이나 token 원문은 표시하지 않고 reference만 표시한다. + +## Decision History + +- 2026-06-24: endpoint/config value 표시 패턴을 `endpoint-tile`로 정의했다. + diff --git a/agent-ui/definition/components/execution-action-toolbar/index.md b/agent-ui/definition/components/execution-action-toolbar/index.md new file mode 100644 index 0000000..6fa8a10 --- /dev/null +++ b/agent-ui/definition/components/execution-action-toolbar/index.md @@ -0,0 +1,70 @@ +--- +ui_doc_type: component +component_id: execution-action-toolbar +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "_buildActionsSection, _ActionButton 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "execution action draft models" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "cancel/report/log/artifact write action audit 후보" +--- + +# Execution Action Toolbar + +Component ID: `execution-action-toolbar` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | `_buildActionsSection`, `_ActionButton` 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | execution action draft models | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | execution write action audit 후보 | + +## Purpose + +확장된 execution에서 cancel, report, append log, append artifact action을 제공한다. + +## Used By + +- `executions`: `executions.action-toolbar` + +## Anatomy + +- Cancel button +- Report button +- Log button +- Artifact button +- per-button submitting/success/failure indicator +- cancel confirmation dialog + +## Variants + +- enabled: runner id가 있고 cancel 상태가 아니며 submitting 중이 아님 +- disabled: runner id 없음, canceled state, submitting + +## States + +- default +- disabled +- submitting +- succeeded +- failed + +## Rules + +- cancel은 confirmation dialog를 거친다. +- raw log line, artifact full path, credential-like error payload를 감사 UI에 복제 노출하지 않는다. +- action outcome은 SDD의 actor/action/target/outcome/timestamp/reason metadata 경계와 맞춰 확장한다. + +## Decision History + +- 2026-06-24: execution write action button group을 `execution-action-toolbar` component로 정의했다. + diff --git a/agent-ui/definition/components/index.md b/agent-ui/definition/components/index.md new file mode 100644 index 0000000..3bfb84e --- /dev/null +++ b/agent-ui/definition/components/index.md @@ -0,0 +1,53 @@ +--- +ui_doc_type: components-index +components: + - console-shell + - console-rail + - section-surface + - state-panel + - status-badge + - endpoint-tile + - connection-status-grid + - auth-token-reference + - record-list + - action-feedback + - runner-self-update-form + - job-create-form + - execution-action-toolbar + - authorization-state + - audit-action-summary + - log-preview + - artifact-list + - agent-chat-panel +--- + +# Component Definitions + +## Component List + +| Component ID | Status | Evidence | Description | +|--------------|--------|----------|-------------| +| `console-shell` | implemented | `oto_console_shell.dart` | overall console scaffold with rail and selected section content | +| `console-rail` | implemented | `oto_console_shell.dart` | section navigation rail | +| `section-surface` | implemented | `oto_console_shell.dart` | generic titled empty/detail section shell | +| `state-panel` | implemented | surface files | loading, empty, error state blocks | +| `status-badge` | implemented | overview/runners/jobs/executions surface files | compact status label badge | +| `endpoint-tile` | implemented | `oto_console_overview.dart` | endpoint or config value tile | +| `connection-status-grid` | implemented | `oto_console_overview.dart` | health/readiness status grid | +| `auth-token-reference` | implemented | `oto_console_overview.dart` | display-only auth token reference | +| `record-list` | implemented | runners/jobs/executions/artifacts surface files | repeated entity list rows | +| `action-feedback` | implemented | runners/jobs/executions surface files | success/deferred/failed action message | +| `runner-self-update-form` | implemented | `oto_runners_surface.dart` | runner self-update draft form | +| `job-create-form` | implemented | `oto_jobs_surface.dart` | job create draft form | +| `execution-action-toolbar` | implemented | `oto_executions_surface.dart` | cancel/report/log/artifact execution actions | +| `authorization-state` | planned | security/audit SDD | operator/admin allow/deny, disabled, and error state rules for write actions | +| `audit-action-summary` | planned | security/audit SDD | display-safe action metadata summary for audit-oriented UI exposure | +| `log-preview` | implemented | `oto_executions_surface.dart` | bounded execution log preview | +| `artifact-list` | implemented | `oto_artifacts_surface.dart`, `oto_executions_surface.dart` | artifact records in tab and execution detail | +| `agent-chat-panel` | implemented | `oto_agent_panel.dart` | agent-shell backed OTO assistant panel | + +## Rules + +- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다. +- view별 변형이 필요하면 `/.md` 또는 하위 디렉터리를 사용한다. +- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다. diff --git a/agent-ui/definition/components/job-create-form/index.md b/agent-ui/definition/components/job-create-form/index.md new file mode 100644 index 0000000..6a0e636 --- /dev/null +++ b/agent-ui/definition/components/job-create-form/index.md @@ -0,0 +1,68 @@ +--- +ui_doc_type: component +component_id: job-create-form +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_jobs_surface.dart + notes: "_buildJobCreateForm 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoJobCreateDraft validation" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "create-job write action audit 후보" +--- + +# Job Create Form + +Component ID: `job-create-form` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart` | `_buildJobCreateForm` 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoJobCreateDraft` validation | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | create-job write action audit 후보 | + +## Purpose + +operator가 job id와 job name으로 새 pipeline/job record 생성을 요청하게 한다. + +## Used By + +- `pipelines`: `pipelines.create-job-form` + +## Anatomy + +- Job ID field +- Job Name field +- Create button +- submitting spinner +- action feedback + +## Variants + +- enabled: id/name이 모두 있고 not submitting +- disabled: 입력 부족 또는 submitting + +## States + +- default +- editing +- submitting +- disabled +- result-visible + +## Rules + +- id와 name이 비어 있으면 submit할 수 없다. +- create 실패 message는 민감 payload 노출 여부를 확인한다. + +## Decision History + +- 2026-06-24: jobs surface의 create form을 `job-create-form` component로 정의했다. + diff --git a/agent-ui/definition/components/log-preview/index.md b/agent-ui/definition/components/log-preview/index.md new file mode 100644 index 0000000..f72986b --- /dev/null +++ b/agent-ui/definition/components/log-preview/index.md @@ -0,0 +1,70 @@ +--- +ui_doc_type: component +component_id: log-preview +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "_buildLogsSection, _buildLogsContent 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoLogEntryViewModel" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "raw log line은 감사 이벤트에 복제하지 않는 기준" +--- + +# Log Preview + +Component ID: `log-preview` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | `_buildLogsSection`, `_buildLogsContent` 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoLogEntryViewModel` | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | raw log line 감사 복제 금지 기준 | + +## Purpose + +선택된 execution의 로그 일부를 bounded monospace preview로 보여준다. + +## Used By + +- `executions`: `executions.logs-preview` + +## Anatomy + +- section title +- black preview container +- timestamped log lines +- loading/empty/error text + +## Variants + +- no logs loaded +- loading +- empty +- error +- data + +## States + +- default +- loading +- empty +- error +- data + +## Rules + +- preview 높이는 제한한다. +- 감사 이벤트나 감사 UI 정의에는 raw log line을 복제하지 않는다. + +## Decision History + +- 2026-06-24: execution detail log preview를 `log-preview` component로 정의했다. + diff --git a/agent-ui/definition/components/record-list/index.md b/agent-ui/definition/components/record-list/index.md new file mode 100644 index 0000000..d42c7e6 --- /dev/null +++ b/agent-ui/definition/components/record-list/index.md @@ -0,0 +1,76 @@ +--- +ui_doc_type: component +component_id: record-list +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart + notes: "runner list rows" + - type: code + path: packages/flutter/oto_console/lib/src/oto_jobs_surface.dart + notes: "job list rows" + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "execution list rows" + - type: code + path: packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart + notes: "artifact list rows" +--- + +# Record List + +Component ID: `record-list` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | runner list rows | +| code | `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart` | job list rows | +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | execution list rows | +| code | `packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart` | artifact list rows | + +## Purpose + +runner, job, execution, artifact 같은 운영 record를 카드형 row 목록으로 스캔하게 한다. + +## Used By + +- `runners`: `runners.runner-list` +- `pipelines`: `pipelines.job-list` +- `executions`: `executions.execution-list`, `executions.execution-detail` +- `artifacts`: `artifacts.artifact-list` + +## Anatomy + +- primary id/name +- secondary metadata +- status badge +- optional inline action/link +- optional expanded detail + +## Variants + +- runner row +- job row +- execution row +- artifact row + +## States + +- default +- expanded +- actionable +- truncated + +## Rules + +- row 안의 id/path/date 값은 긴 문자열을 ellipsis 처리한다. +- execution row 확장 시 action/log/artifact 영역은 definition region과 함께 갱신한다. + +## Decision History + +- 2026-06-24: 반복 row 목록을 `record-list` component로 정의했다. + diff --git a/agent-ui/definition/components/runner-self-update-form/index.md b/agent-ui/definition/components/runner-self-update-form/index.md new file mode 100644 index 0000000..3a6152d --- /dev/null +++ b/agent-ui/definition/components/runner-self-update-form/index.md @@ -0,0 +1,68 @@ +--- +ui_doc_type: component +component_id: runner-self-update-form +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart + notes: "_buildSelfUpdateForm 구현" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_contract.dart + notes: "OtoRunnerSelfUpdateDraft validation" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "self-update-runner write action audit 후보" +--- + +# Runner Self Update Form + +Component ID: `runner-self-update-form` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | `_buildSelfUpdateForm` 구현 | +| code | `packages/flutter/oto_console/lib/src/oto_console_contract.dart` | `OtoRunnerSelfUpdateDraft` validation | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | self-update write action audit 후보 | + +## Purpose + +runner별 target version과 HTTPS download URL을 받아 self-update action을 제출한다. + +## Used By + +- `runners`: `runners.self-update-form` + +## Anatomy + +- version text field +- download URL text field +- Update button +- inline submitting spinner +- action feedback + +## Variants + +- enabled: version과 HTTPS URL이 유효하고 handler가 있음 +- disabled: 입력 부족, HTTP URL, submitting, handler 없음 + +## States + +- default +- editing +- submitting +- disabled +- result-visible + +## Rules + +- download URL은 `https://`로 시작해야 한다. +- private release credential 원문을 문서나 UI fixture에 남기지 않는다. + +## Decision History + +- 2026-06-24: runner self-update form을 독립 component로 정의했다. + diff --git a/agent-ui/definition/components/section-surface/index.md b/agent-ui/definition/components/section-surface/index.md new file mode 100644 index 0000000..5f472db --- /dev/null +++ b/agent-ui/definition/components/section-surface/index.md @@ -0,0 +1,68 @@ +--- +ui_doc_type: component +component_id: section-surface +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "OtoConsoleSectionSurface 구현" + - type: docs + path: apps/client/README.md + notes: "console package embedding" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Section Surface + +Component ID: `section-surface` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | `OtoConsoleSectionSurface` 구현 | +| docs | `apps/client/README.md` | console package embedding | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +아직 전용 surface가 없거나 fallback으로 표시하는 section의 제목, empty state, detail rows를 한 구조로 보여준다. + +## Used By + +- `settings`: `settings.header`, `settings.state-panel`, `settings.endpoint-details` +- shell fallback for `runners`, `pipelines`, `executions`, `artifacts` + +## Anatomy + +- section icon +- section title +- empty state panel +- optional detail tiles + +## Variants + +- default: empty panel only +- details: HTTP API, Wire URL, browser API policy 같은 detail tiles 포함 + +## States + +- default +- empty +- detail-present +- error: 없음 +- disabled: 없음 + +## Rules + +- 전용 view 구현이 없을 때만 fallback으로 사용한다. +- detail 값은 한 줄 ellipsis로 표시한다. + +## Decision History + +- 2026-06-24: shell fallback surface를 `section-surface` component로 정의했다. + diff --git a/agent-ui/definition/components/state-panel/index.md b/agent-ui/definition/components/state-panel/index.md new file mode 100644 index 0000000..4b157d7 --- /dev/null +++ b/agent-ui/definition/components/state-panel/index.md @@ -0,0 +1,75 @@ +--- +ui_doc_type: component +component_id: state-panel +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart + notes: "runner empty/error state panel" + - type: code + path: packages/flutter/oto_console/lib/src/oto_jobs_surface.dart + notes: "jobs empty/error state panel" + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "executions empty/error state panel" + - type: code + path: packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart + notes: "artifacts empty/error state panel" +--- + +# State Panel + +Component ID: `state-panel` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | runner empty/error state panel | +| code | `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart` | jobs empty/error state panel | +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | executions empty/error state panel | +| code | `packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart` | artifacts empty/error state panel | + +## Purpose + +surface snapshot의 loading, empty, error 상태를 같은 밀도와 테두리 스타일로 보여준다. + +## Used By + +- `runners`: `runners.state-panel` +- `pipelines`: `pipelines.state-panel` +- `executions`: `executions.state-panel` +- `artifacts`: `artifacts.state-panel` +- `settings`: `settings.state-panel` + +## Anatomy + +- icon +- title +- message +- optional progress indicator for loading + +## Variants + +- loading: centered progress indicator +- empty: neutral panel +- error: red tinted panel + +## States + +- loading +- empty +- error +- permission-denied: planned extension candidate + +## Rules + +- error message는 snapshot `errorMessage`가 있으면 사용하고 없으면 unknown fallback을 쓴다. +- permission-denied를 추가하면 권한/감사 SDD 기준의 민감 payload 미노출을 따라야 한다. + +## Decision History + +- 2026-06-24: 여러 surface의 empty/error 반복 UI를 `state-panel`로 정의했다. + diff --git a/agent-ui/definition/components/status-badge/index.md b/agent-ui/definition/components/status-badge/index.md new file mode 100644 index 0000000..a669a2f --- /dev/null +++ b/agent-ui/definition/components/status-badge/index.md @@ -0,0 +1,74 @@ +--- +ui_doc_type: component +component_id: status-badge +status: implemented +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_overview.dart + notes: "connection status badge" + - type: code + path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart + notes: "runner status badge" + - type: code + path: packages/flutter/oto_console/lib/src/oto_jobs_surface.dart + notes: "job state badge" + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "execution state badge" +--- + +# Status Badge + +Component ID: `status-badge` + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_overview.dart` | connection status badge | +| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | runner status badge | +| code | `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart` | job state badge | +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | execution state badge | + +## Purpose + +상태를 짧은 uppercase label과 색으로 스캔 가능하게 표시한다. + +## Used By + +- `overview`: `overview.header` +- `runners`: `runners.runner-list` +- `pipelines`: `pipelines.job-list` +- `executions`: `executions.execution-list` + +## Anatomy + +- label text +- colored container +- optional dot in overview variant + +## Variants + +- connection: checking/online/degraded/offline +- runner: active/online/idle/busy/running/offline +- work item: queued/running/succeeded/failed/canceled + +## States + +- default +- success +- warning +- failure +- neutral + +## Rules + +- label은 한 줄로 줄이고 긴 값은 ellipsis 처리한다. +- semantic color는 surface별 mapping과 일치해야 한다. + +## Decision History + +- 2026-06-24: surface별 private badge 구현을 공통 UI component로 문서화했다. + diff --git a/agent-ui/definition/index.md b/agent-ui/definition/index.md new file mode 100644 index 0000000..bfa6407 --- /dev/null +++ b/agent-ui/definition/index.md @@ -0,0 +1,63 @@ +--- +ui_doc_type: definition-index +surface_type: ops-dev +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "OtoConsoleShell, rail navigation, fallback section surface 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "Host MaterialApp이 overview/runners/pipelines/executions/artifacts surface를 mount" + - type: docs + path: agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md + notes: "운영 보안, 감사, UI 노출 범위가 현재 Milestone에 정의됨" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "auth token reference, action outcome, 감사 metadata 노출/마스킹 기준" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# UI Definition + +## Purpose + +OTO Control Plane Flutter 콘솔의 운영 화면, 반복 component, 상태 표현, write action 결과 표면을 agent와 사람이 같은 기준으로 읽을 수 있게 고정한다. + +## Surface Type + +- Type: ops-dev +- Notes: 현재는 운영자용 Control Plane 콘솔을 다룬다. product UI 레이어는 요청될 때 brand/content/assets/tokens/motion 문서로 확장한다. + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | `OtoConsoleShell`, rail navigation, fallback section surface 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | host app이 콘솔 section surface를 실제 mount | +| docs | `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md` | 운영 보안, 감사, UI 노출 범위 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | auth token reference와 audit metadata 노출/마스킹 기준 | +| user | 없음 | agent-ui 생성 요청 | + +## Structure + +- `views/`: 화면 또는 업무 단위 정의 +- `components/`: 반복 UI 구성요소 정의 +- `archive/`: 현재 기준이 아닌 과거 정의/결정 로그 + +## Reading Rules + +- 현재 UI 동기화는 이 디렉터리의 활성 문서를 기준으로 한다. +- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다. + +## Sync Rules + +- frame-view가 있으면 view region id와 frame region id는 동일해야 한다. +- view에서 참조한 component id는 `components/` 아래에 정의되어야 한다. +- frame은 definition을 대체하지 않는다. +- 문서 계획만 있는 보안/감사 항목은 구현 완료 상태로 쓰지 않는다. + +## Decision History + +- 2026-06-24: Flutter 콘솔 구현을 기준으로 `code-first` agent-ui scaffold를 생성했다. diff --git a/agent-ui/definition/views/agent/index.md b/agent-ui/definition/views/agent/index.md new file mode 100644 index 0000000..c8c005f --- /dev/null +++ b/agent-ui/definition/views/agent/index.md @@ -0,0 +1,90 @@ +--- +ui_doc_type: view +view_id: agent +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_agent_panel.dart + notes: "OtoAgentPanel이 agent_shell AgentShell을 mount" + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "agent section fallback으로 OtoAgentPanel 사용" + - type: docs + path: apps/client/README.md + notes: "oto_console package를 다른 Flutter host에 embed 가능" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - agent.conversation + - agent.capabilities + - agent.input +--- + +# Agent + +View ID: `agent` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_agent_panel.dart` | `OtoAgentPanel`이 `AgentShell`을 mount | +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | agent section fallback | +| docs | `apps/client/README.md` | `oto_console` embedding 기준 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +OTO capability context를 agent-shell 대화 표면에 연결한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- OTO capability summary 확인 +- agent prompt submit + +## Information Priority + +1. assistant intro message +2. registered capabilities +3. prompt input + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `agent.conversation` | agent message timeline | `agent-chat-panel` | high | intro message 표시 | +| `agent.capabilities` | registered capabilities 요약 | `agent-chat-panel` | medium | capability pack이 있을 때 포함 | +| `agent.input` | prompt input | `agent-chat-panel` | medium | placeholder: `Ask about OTO builds` | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `agent.submit` | prompt submit | `onSubmit` callback 호출 | handler 존재 | + +## States + +- loading: 현재 구현은 `busy: false`로 고정되어 별도 loading state가 없다. +- empty: capabilities가 없으면 intro message만 표시한다. +- error: 현재 구현에는 별도 error state가 없다. +- permission-denied: 현재 구현에는 별도 denied state가 없다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: agent-shell mount 영역을 agent view로 정의했다. diff --git a/agent-ui/definition/views/artifacts/index.md b/agent-ui/definition/views/artifacts/index.md new file mode 100644 index 0000000..f292446 --- /dev/null +++ b/agent-ui/definition/views/artifacts/index.md @@ -0,0 +1,91 @@ +--- +ui_doc_type: view +view_id: artifacts +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart + notes: "OtoArtifactsSurface 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "artifact snapshot 연결" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "artifact path와 내용 노출은 감사 UI 마스킹 기준에서 주의" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - artifacts.header + - artifacts.state-panel + - artifacts.artifact-list +--- + +# Artifacts + +View ID: `artifacts` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_artifacts_surface.dart` | `OtoArtifactsSurface` 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | artifact snapshot 연결 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | artifact path와 내용 노출 주의 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Control Plane에 수집된 artifact event를 목록으로 확인한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- artifact name 확인 +- artifact path 확인 +- empty/error 상태 확인 + +## Information Priority + +1. artifact name +2. artifact path +3. snapshot state + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `artifacts.header` | 화면 제목 | 없음 | high | `Artifacts` | +| `artifacts.state-panel` | loading/empty/error 표현 | `state-panel` | high | snapshot state 기준 | +| `artifacts.artifact-list` | artifact row 목록 | `artifact-list` | high | name과 path 표시 | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| 없음 | - | - | - | + +## States + +- loading: 중앙 progress indicator. +- empty: `No artifacts` state panel. +- error: `Error loading artifacts` state panel과 snapshot error message. +- permission-denied: 현재 구현에는 별도 denied state가 없다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: artifact event list를 단일 주 region으로 정의했다. diff --git a/agent-ui/definition/views/executions/index.md b/agent-ui/definition/views/executions/index.md new file mode 100644 index 0000000..b3a310d --- /dev/null +++ b/agent-ui/definition/views/executions/index.md @@ -0,0 +1,113 @@ +--- +ui_doc_type: view +view_id: executions +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_executions_surface.dart + notes: "OtoExecutionsSurface 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "execution actions, logs, artifacts snapshot 연결" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "execution cancel/report/log/artifact write action과 감사 노출 경계" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - executions.header + - executions.state-panel + - executions.execution-list + - executions.execution-detail + - executions.action-toolbar + - executions.action-feedback + - executions.logs-preview + - executions.artifacts-preview +--- + +# Executions + +View ID: `executions` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_executions_surface.dart` | `OtoExecutionsSurface` 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | execution actions, logs, artifacts snapshot 연결 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | execution write action과 감사 노출 경계 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +execution 상태를 확인하고, 상세 영역에서 cancel/report/log/artifact write action과 log/artifact preview를 조작한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- execution 목록과 상태 확인 +- execution detail 확장/접기 +- cancel/report/log/artifact action submit +- logs preview와 artifacts preview 확인 +- artifacts tab으로 이동 + +## Information Priority + +1. execution id, job id, runner id, state +2. action toolbar와 결과 feedback +3. logs/artifacts preview + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `executions.header` | 화면 제목 | 없음 | high | `Executions` | +| `executions.state-panel` | loading/empty/error 표현 | `state-panel` | high | snapshot state 기준 | +| `executions.execution-list` | execution row 목록 | `record-list` | high | expandable row | +| `executions.execution-detail` | 확장된 execution 상세 | `record-list` | high | actions, logs, artifacts 포함 | +| `executions.action-toolbar` | cancel/report/log/artifact action | `execution-action-toolbar` | high | runner id 존재, not canceled, not submitting | +| `executions.action-feedback` | action 결과 표시 | `action-feedback` | medium | success/failed | +| `executions.logs-preview` | execution log preview | `log-preview` | medium | raw log 원문 복제 노출은 SDD 기준에서 주의 | +| `executions.artifacts-preview` | execution artifact preview | `artifact-list` | medium | artifact path 민감도는 SDD 기준에서 주의 | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `executions.toggle-detail` | execution row tap | detail expand/collapse | execution id 존재 | +| `executions.cancel` | Cancel button and confirmation | cancel execution draft submit | runner id 존재, not canceled, not submitting | +| `executions.report` | Report button | report execution draft submit | runner id 존재, not canceled, not submitting | +| `executions.append-log` | Log button | append log draft submit | runner id 존재, not canceled, not submitting | +| `executions.append-artifact` | Artifact button | append artifact draft submit | runner id 존재, not canceled, not submitting | +| `executions.view-artifacts` | View Artifacts Tab | `artifacts` view로 이동 | navigation handler 존재 | + +## States + +- loading: 중앙 progress indicator. +- empty: `No executions` state panel. +- error: `Error loading executions` state panel과 snapshot error message. +- permission-denied: planned `authorization-state` component에서 operator/admin 권한 실패를 display-safe message로 표현한다. + +## Planned Extensions + +- `authorization-state`: cancel/report/log/artifact action의 허용/거부, disabled/error 상태. +- `audit-action-summary`: cancel/report/log/artifact action의 actor/action/target/outcome/timestamp/reason metadata 요약. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: execution detail과 action toolbar를 주요 region으로 정의했다. diff --git a/agent-ui/definition/views/index.md b/agent-ui/definition/views/index.md new file mode 100644 index 0000000..e7950a3 --- /dev/null +++ b/agent-ui/definition/views/index.md @@ -0,0 +1,52 @@ +--- +ui_doc_type: views-index +views: + - overview + - runners + - pipelines + - executions + - artifacts + - agent + - settings +--- + +# View Definitions + +## View Tree + +| View ID | Status | Evidence | Description | +|---------|--------|----------|-------------| +| `overview` | implemented | `OtoConsoleOverview` | Control Plane endpoint, connection, authentication reference overview | +| `runners` | implemented | `OtoRunnersSurface` | runner registry state and self-update action surface | +| `pipelines` | implemented | `OtoJobsSurface` | pipeline/job queue list and create job action surface | +| `executions` | implemented | `OtoExecutionsSurface` | execution list, detail expansion, write actions, log/artifact preview | +| `artifacts` | implemented | `OtoArtifactsSurface` | artifact event list | +| `agent` | implemented | `OtoAgentPanel` | embeddable agent-shell panel for OTO capabilities | +| `settings` | implemented | `OtoConsoleShell` fallback section | runtime endpoint and browser policy details | + +## Navigation + +- `overview` -> `runners`: rail navigation +- `overview` -> `pipelines`: rail navigation +- `overview` -> `executions`: rail navigation +- `overview` -> `artifacts`: rail navigation +- `overview` -> `agent`: rail navigation +- `overview` -> `settings`: rail navigation +- `pipelines` -> `executions`: job execution id tap +- `executions` -> `artifacts`: "View Artifacts Tab" action + +## Common States + +- loading +- empty +- error +- permission-denied + +## Common Permissions + +- operator/admin: write action submit 가능 여부를 제어하는 최소 역할 후보. 현재 SDD 기준은 단일 역할과 표시 가능한 token reference다. + +## Open Questions + +- 없음 + diff --git a/agent-ui/definition/views/overview/index.md b/agent-ui/definition/views/overview/index.md new file mode 100644 index 0000000..71fc21c --- /dev/null +++ b/agent-ui/definition/views/overview/index.md @@ -0,0 +1,96 @@ +--- +ui_doc_type: view +view_id: overview +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_overview.dart + notes: "OtoConsoleOverview 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "host app에서 overview surface mount" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "auth token reference는 표시 가능한 reference만 노출" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - overview.header + - overview.endpoints + - overview.connection-status + - overview.authentication + - overview.actions +--- + +# Overview + +View ID: `overview` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_overview.dart` | `OtoConsoleOverview` 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | host app에서 overview surface mount | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | auth token reference 표시 기준 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Control Plane의 API endpoint, Core 연결 상태, authentication reference를 운영자가 한 화면에서 확인하게 한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- HTTP/Wire endpoint 확인 +- health/readiness 연결 상태 확인 +- 표시 가능한 auth token reference 확인 +- Core status refresh 실행 + +## Information Priority + +1. Core online/degraded/offline 상태 +2. HTTP/Wire endpoint와 browser API policy +3. auth token reference와 refresh action + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `overview.header` | 화면 제목과 연결 상태 badge | `status-badge` | high | `Build Operations Overview`와 connection label | +| `overview.endpoints` | HTTP/Wire endpoint와 policy 표시 | `endpoint-tile` | high | config와 connection policy note 기준 | +| `overview.connection-status` | health/readiness 상태 grid | `connection-status-grid` | high | checking/online/degraded/offline | +| `overview.authentication` | active auth token reference 표시 | `auth-token-reference` | medium | token 원문이 아니라 reference만 표시 | +| `overview.actions` | refresh action | 없음 | medium | `onRefresh`가 있을 때만 표시 | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `overview.refresh` | Refresh button | Core connection snapshot reload | `onRefresh != null` | + +## States + +- loading: connection state가 `checking`일 때 status badge와 endpoint tiles에 checking 상태를 표시한다. +- empty: endpoint 설정은 있으나 Core 응답 데이터가 없으면 degraded/offline 상태로 표현한다. +- error: health/readiness error message를 connection status tile에 표시한다. +- permission-denied: 현재 구현에는 별도 denied state가 없으며 SDD의 권한 실패 UX 확장 후보로 둔다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: 구현 코드와 SDD 기준으로 overview region을 정의했다. diff --git a/agent-ui/definition/views/pipelines/index.md b/agent-ui/definition/views/pipelines/index.md new file mode 100644 index 0000000..d029342 --- /dev/null +++ b/agent-ui/definition/views/pipelines/index.md @@ -0,0 +1,103 @@ +--- +ui_doc_type: view +view_id: pipelines +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_jobs_surface.dart + notes: "OtoJobsSurface 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "job snapshot, create action, execution navigation 연결" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "create-job은 write action 감사 후보" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - pipelines.header + - pipelines.create-job-form + - pipelines.state-panel + - pipelines.job-list + - pipelines.execution-link + - pipelines.action-feedback +--- + +# Pipelines + +View ID: `pipelines` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart` | `OtoJobsSurface` 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | job snapshot, create action, execution navigation 연결 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | create-job write action 경계 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +pipeline/job queue를 확인하고, 새 job을 만들며, 연결된 execution으로 이동한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- job 목록과 상태 확인 +- job id/name 기반 create 요청 +- execution id가 있는 job에서 executions view로 이동 + +## Information Priority + +1. create job form 상태 +2. job list와 상태 badge +3. execution link + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `pipelines.header` | 화면 제목 | 없음 | high | `Pipelines / Jobs` | +| `pipelines.create-job-form` | job create draft 입력 | `job-create-form` | high | job id/name 필수 | +| `pipelines.state-panel` | loading/empty/error 표현 | `state-panel` | high | snapshot state 기준 | +| `pipelines.job-list` | job row 목록 | `record-list` | high | name, id, state, created/updated | +| `pipelines.execution-link` | execution detail 이동 | 없음 | medium | execution id가 있을 때 표시 | +| `pipelines.action-feedback` | job create 결과 표시 | `action-feedback` | medium | success/failed | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `pipelines.create-job` | Create button | job create draft submit | job id/name 입력, not submitting | +| `pipelines.open-execution` | execution id chip | `executions` view로 이동 | job execution id 존재 | + +## States + +- loading: 중앙 progress indicator. +- empty: `No pipeline jobs` state panel. +- error: `Error loading jobs` state panel과 snapshot error message. +- permission-denied: planned `authorization-state` component에서 operator/admin 권한 실패를 display-safe message로 표현한다. + +## Planned Extensions + +- `authorization-state`: create job action의 허용/거부, disabled/error 상태. +- `audit-action-summary`: create job action의 actor/action/target/outcome/timestamp/reason metadata 요약. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: job create form과 job list를 주요 region으로 정의했다. diff --git a/agent-ui/definition/views/runners/index.md b/agent-ui/definition/views/runners/index.md new file mode 100644 index 0000000..24fa9d3 --- /dev/null +++ b/agent-ui/definition/views/runners/index.md @@ -0,0 +1,101 @@ +--- +ui_doc_type: view +view_id: runners +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart + notes: "OtoRunnersSurface 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "runner snapshot과 self-update action 연결" + - type: docs + path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md + notes: "runner self-update는 write action 감사 후보" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - runners.header + - runners.state-panel + - runners.runner-list + - runners.self-update-form + - runners.action-feedback +--- + +# Runners + +View ID: `runners` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | `OtoRunnersSurface` 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | runner snapshot과 self-update action 연결 | +| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | runner self-update write action 경계 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +등록된 runner 상태를 보고, runner별 self-update 요청을 제출하며, action 결과를 확인한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- runner registry 상태 확인 +- active job/execution 확인 +- self-update version과 HTTPS download URL 제출 +- success/deferred/failed 결과 확인 + +## Information Priority + +1. runner id와 status +2. active job/execution context +3. self-update form과 action feedback + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `runners.header` | 화면 제목 | 없음 | high | `Runners` | +| `runners.state-panel` | loading/empty/error 표현 | `state-panel` | high | snapshot state 기준 | +| `runners.runner-list` | runner row 목록 | `record-list` | high | runner id, alias, message, current job/execution | +| `runners.self-update-form` | runner self-update draft 입력 | `runner-self-update-form` | high | version, HTTPS download URL | +| `runners.action-feedback` | self-update 결과 표시 | `action-feedback` | medium | success/deferred/failed | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `runners.self-update` | Update button | runner self-update draft submit | version 값, HTTPS URL, handler 존재, not submitting | + +## States + +- loading: 중앙 progress indicator. +- empty: `No runners connected` state panel. +- error: `Error loading runners` state panel과 snapshot error message. +- permission-denied: planned `authorization-state` component에서 operator/admin 권한 실패를 display-safe message로 표현한다. + +## Planned Extensions + +- `authorization-state`: self-update action의 허용/거부, disabled/error 상태. +- `audit-action-summary`: self-update action의 actor/action/target/outcome/timestamp/reason metadata 요약. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: runner list와 self-update form을 주요 region으로 정의했다. diff --git a/agent-ui/definition/views/settings/index.md b/agent-ui/definition/views/settings/index.md new file mode 100644 index 0000000..a7ec4b4 --- /dev/null +++ b/agent-ui/definition/views/settings/index.md @@ -0,0 +1,91 @@ +--- +ui_doc_type: view +view_id: settings +status: implemented +frame: null +source_evidence: + - type: code + path: packages/flutter/oto_console/lib/src/oto_console_shell.dart + notes: "settings section fallback surface 구현" + - type: code + path: apps/client/lib/src/app/oto_client_app.dart + notes: "host app은 settings override를 넘기지 않아 fallback surface 사용" + - type: docs + path: apps/client/README.md + notes: "preview port와 server URL 설정 기준" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - settings.header + - settings.state-panel + - settings.endpoint-details +--- + +# Settings + +View ID: `settings` + +Frame: +- 없음 + +Status: `implemented` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | settings section fallback surface 구현 | +| code | `apps/client/lib/src/app/oto_client_app.dart` | settings override 없이 fallback 사용 | +| docs | `apps/client/README.md` | preview port와 server URL 설정 기준 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +런타임 endpoint와 browser API policy 같은 local preference/환경 정보를 확인한다. + +## Primary Users + +- operator/admin +- local developer + +## Primary Tasks + +- HTTP API endpoint 확인 +- Wire URL 확인 +- browser API policy 확인 + +## Information Priority + +1. HTTP API endpoint +2. Wire URL +3. browser API policy + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `settings.header` | 화면 제목 | `section-surface` | high | `Settings` | +| `settings.state-panel` | fallback empty state | `state-panel` | medium | local preferences 없음 | +| `settings.endpoint-details` | endpoint and policy details | `endpoint-tile` | high | config가 있을 때 HTTP/Wire 표시 | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| 없음 | - | - | - | + +## States + +- loading: 현재 구현에는 별도 loading state가 없다. +- empty: `No local preferences` state panel. +- error: 현재 구현에는 별도 error state가 없다. +- permission-denied: 현재 구현에는 별도 denied state가 없다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-24: shell fallback settings surface를 view로 정의했다. diff --git a/agent-ui/frame/index.md b/agent-ui/frame/index.md new file mode 100644 index 0000000..d63f9ce --- /dev/null +++ b/agent-ui/frame/index.md @@ -0,0 +1,23 @@ +--- +ui_doc_type: frame-index +frames: [] +--- + +# UI Frames + +## Purpose + +이 디렉터리는 visual source가 있는 view의 wireframe과 definition 연결 정보를 보관한다. +현재 visual source가 있는 view는 없다. + +## Frame Sources + +- `views//index.md`: visual source가 있는 view의 frame 연결 문서 +- `views//wire.excalidraw`: 선택 visual source + +## Rules + +- frame은 definition을 대체하지 않는다. +- visual source가 있으면 대응되는 frame index에 기록한다. +- visual source가 없으면 `views//`를 만들지 않는다. +- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다.