From d18463ea80ba9360e4326e8cbd247dc891c9e219 Mon Sep 17 00:00:00 2001 From: toki Date: Tue, 2 Jun 2026 19:38:06 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= =?UTF-8?q?=EB=90=9C=20=EB=AC=B8=EC=84=9C=20=EB=B3=80=EA=B2=BD=EC=82=AC?= =?UTF-8?q?=ED=95=AD=20=EC=A0=81=EC=9A=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 120 +++++------------------- docs/ios-notification-test-guide.md | 60 ++++++------ docs/linux-notification-test-guide.md | 50 +++++----- docs/macos-notification-test-guide.md | 49 +++++----- docs/runtime-image-validation.md | 70 +++++++------- docs/windows-notification-test-guide.md | 50 +++++----- 6 files changed, 151 insertions(+), 248 deletions(-) diff --git a/docs/README.md b/docs/README.md index a29e28e8..d65917c3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,109 +1,31 @@ -# nexo Docs +# nexo 문서 색인 -This directory holds product notes, migration decisions, and operational -documentation that apply to more than one module. +`docs/`는 모든 사용자가 처음부터 끝까지 읽어야 하는 필수 문서 모음이 아니다. 루트 `README.md`가 워크스페이스의 기본 안내이고, 이 디렉터리는 특정 상황에서 참고할 공개 문서와 검증 기록을 둔다. -Module-specific instructions stay with the module that owns them. +## 먼저 읽을 문서 -## Runtime Baseline Index +- 전체 프로젝트 개요와 기본 개발 흐름: `../README.md` +- 작업 규칙과 agent 진입 절차: `../AGENTS.md` -- Workspace runtime and upstream policy: `../README.md` -- Core compose runtime, deploy loop, smoke checks, remote parity, and secret boundary: - `../services/core/compose/README.md` -- Core upstream snapshot baseline: `../services/core/UPSTREAM.md` -- Mattermost mobile app upstream snapshot baseline: `../apps/mattermost/UPSTREAM.md` -- Mattermost push-proxy upstream snapshot baseline: `../services/push-proxy/UPSTREAM.md` -- Runtime Image Validation details: `runtime-image-validation.md` -- Notification access preparation: - `ios-notification-test-guide.md`, - `macos-notification-test-guide.md`, - `windows-notification-test-guide.md`, - `linux-notification-test-guide.md` +## 필요할 때 읽는 문서 -## Upstream Following Policy +| 문서 | 읽는 경우 | +|---|---| +| `ios-notification-test-guide.md` | iOS 알림 smoke를 위해 Apple/Firebase/기기 준비 항목을 정할 때 | +| `macos-notification-test-guide.md` | macOS 알림 smoke를 위해 runner, signing, push 범위를 정할 때 | +| `windows-notification-test-guide.md` | Windows 알림 smoke를 위해 runner, packaging, signing 방식을 정할 때 | +| `linux-notification-test-guide.md` | Linux 알림 smoke를 위해 runner와 desktop notification 환경을 정할 때 | +| `runtime-image-validation.md` | runtime image tag, digest, compose smoke 증거를 확인하거나 갱신할 때 | -Mattermost upstream repositories are runtime baselines, not the main nexo -product surface. Keep `apps/mattermost`, `services/core`, and -`services/push-proxy` close to their recorded upstream snapshots, and put -nexo-owned behavior in the Flutter SDK, compose/runtime wrappers, docs, or -small explicit compatibility patches. +## 모듈별 문서 -### Baseline Records +특정 모듈 안에서만 필요한 내용은 해당 모듈의 문서를 우선한다. -Each upstream snapshot owner keeps an `UPSTREAM.md` file with: +- Core compose runtime: `../services/core/compose/README.md` +- Core upstream 기준선: `../services/core/UPSTREAM.md` +- Mattermost mobile upstream 기준선: `../apps/mattermost/UPSTREAM.md` +- Mattermost push-proxy upstream 기준선: `../services/push-proxy/UPSTREAM.md` -- source repository URL; -- tracked branch and release tag when applicable; -- exact upstream commit SHA; -- snapshot date; -- snapshot source and target path; -- accepted nexo-local patch boundary; -- update gate and smoke evidence expected before a merge request. +## 중복 방지 -When a baseline changes, update the matching `UPSTREAM.md` in the same change -as the snapshot. Do not mix app, core, and push-proxy snapshot updates in one -merge request. - -### Snapshot Script Contract - -A workspace snapshot helper may automate only the mechanical staging and copy -steps. Its contract is: - -- update the external `mattermost/` staging clone for one selected upstream - repository at a time; -- read the tracked branch from the module's `UPSTREAM.md` or project rules; -- copy the chosen snapshot only to the matching target directory; -- exclude `.git`, dependency caches, build outputs, runtime data, logs, and - ignored secret-bearing files; -- record the selected upstream commit SHA for the operator to apply to the - matching `UPSTREAM.md`; -- print the follow-up diff review and smoke checklist. - -The helper must not commit, push, update multiple upstream repositories in one -run, promote runtime images, or auto-merge staging pull results into this -workspace. Snapshot diff review and smoke verification remain separate gates. - -### Push-Proxy Baseline - -Current choice: keep `services/push-proxy` as a source snapshot mirror of -`mattermost-push-proxy`, and build nexo-owned runtime images from that source -when needed. Runtime image tags and digests are deployment evidence, not the -source baseline. - -Image-only tracking is allowed only after a separate roadmap decision when no -local source build, patch, config packaging, or smoke diagnosis needs the -source snapshot. If that decision changes, update `services/push-proxy/UPSTREAM.md` -and this section together. - -### Release Watch - -Check Mattermost server/webapp monthly releases, active ESR updates, security -notices, Mattermost mobile updates used for verification, and push-proxy -releases before opening a baseline update. Security patches are triaged as soon -as they are noticed; normal monthly or ESR refreshes can wait for an explicit -snapshot lane. - -The public record for a release watch is the relevant `UPSTREAM.md` plus -sanitized runtime evidence in `runtime-image-validation.md` when images or -compose inputs change. Raw credentials, private endpoints, and environment -values stay out of tracked docs. - -### Patch Policy - -Webapp branding and feature visibility changes must stay thin: prefer upstream -configuration, feature flags, small compatibility wrappers, or isolated style -patches. Do not rewrite the webapp into a nexo-owned product surface in this -runtime baseline. - -Do not apply bulk renames, package-wide reformatting, repository reshaping, or -deep fork changes to upstream-owned server, webapp, app, or push-proxy code -without a separate roadmap decision. Exceptions require an explicit rollback -path and a note explaining why an upstream-compatible wrapper is insufficient. - -Classify upstream features during refresh as: - -- `keep`: compatible with nexo runtime and low maintenance cost; -- `hide`: available upstream but disabled or hidden by configuration or a thin - patch; -- `defer`: not adopted until SDK, compose, or app compatibility is ready; -- `remove`: excluded only with a documented compatibility or security reason. +제품 경계, upstream 추적 정책, 개발 명령, 운영 업데이트 흐름은 루트 `README.md`에 둔다. `docs/README.md`는 그 내용을 반복하지 않고 문서 위치와 읽는 상황만 안내한다. diff --git a/docs/ios-notification-test-guide.md b/docs/ios-notification-test-guide.md index 1de28cc4..a69180cb 100644 --- a/docs/ios-notification-test-guide.md +++ b/docs/ios-notification-test-guide.md @@ -1,44 +1,38 @@ -# iOS Notification Credential Preparation +# iOS 알림 인증 준비 가이드 -Last verified: 2026-06-02 +마지막 확인일: 2026-06-02 -Read this when you need to provide Apple/Firebase access so an agent can finish -iOS notification implementation and smoke verification. You do not need to run -the test from this document. +에이전트가 iOS 알림 구현과 smoke 검증을 마무리하려면 Apple/Firebase 접근 정보가 필요하다. 이 문서는 사용자가 무엇을 준비해야 하는지 정리한 가이드이며, 사용자가 직접 이 문서만 보고 테스트를 실행할 필요는 없다. -## Provide +## 준비할 항목 -| Needed | What to prepare | +| 항목 | 준비 내용 | |---|---| -| Apple Team | The Apple Developer Team that owns the smoke app. | -| Bundle ID | A Bundle ID reserved for the iOS smoke app. | -| Signing path | Either allow automatic signing or provide the provisioning profile path privately. | -| Push capability | Enable Push Notifications for the App ID. | -| APNs credential | Prefer APNs auth key `.p8` plus Key ID and Team ID; certificate is a fallback. | -| Firebase app | Create/select the Firebase iOS app with the exact same Bundle ID. | -| Firebase plist | Provide `GoogleService-Info.plist` privately for `apps/flutter-test/ios/Runner/`. | -| Physical device | Provide an installable iPhone/iPad or define who operates it remotely. | -| Send path | Choose Firebase Console, FCM HTTP v1, or an existing private sender. | -| Evidence path | Choose where sanitized logs/screenshots/run notes should be stored. | +| Apple Team | smoke 앱을 소유할 Apple Developer Team을 정한다. | +| Bundle ID | iOS smoke 앱에 사용할 Bundle ID를 예약한다. | +| Signing 방식 | 자동 signing을 허용하거나 provisioning profile 경로를 비공개로 제공한다. | +| Push capability | App ID에 Push Notifications capability를 활성화한다. | +| APNs 인증 | APNs auth key `.p8`, Key ID, Team ID 조합을 우선 사용한다. certificate 방식은 대안으로 둔다. | +| Firebase 앱 | 동일한 Bundle ID로 Firebase iOS 앱을 새로 만들거나 기존 앱을 선택한다. | +| Firebase plist | `GoogleService-Info.plist`를 `apps/flutter-test/ios/Runner/`에 비공개로 제공한다. | +| 실제 기기 | 설치 가능한 iPhone/iPad를 준비하거나 원격으로 누가 조작할지 정한다. | +| 발송 경로 | Firebase Console, FCM HTTP v1, 기존 비공개 sender 중 하나를 선택한다. | +| 증거 위치 | 민감값을 제거한 로그, 스크린샷, 실행 메모를 어디에 남길지 정한다. | -## Do Not Put In Tracked Files +## tracked 파일에 넣지 말아야 할 값 -- Apple Team ID, private Bundle ID, provisioning profile, `.p8`, `.p12`, Key ID, - certificate, or Apple account values. -- `GoogleService-Info.plist` or service-account JSON. -- APNs device token, FCM token, auth token, private endpoint, channel name, user - name, or server URL. +- Apple Team ID, 비공개 Bundle ID, provisioning profile, `.p8`, `.p12`, Key ID, certificate, Apple 계정 값 +- `GoogleService-Info.plist` 또는 service-account JSON +- APNs device token, FCM token, auth token, 비공개 endpoint, channel name, user name, server URL -## Agent Can Then +## 준비 후 에이전트가 할 수 있는 일 -- configure the local iOS host app with the selected signing and Bundle ID; -- place the private Firebase plist in the ignored local path; -- implement or verify APNs registration, token handoff, and open routing; -- run or coordinate the smoke through the approved send path; -- record sanitized evidence in the task or private run note. +- 선택된 signing 방식과 Bundle ID로 로컬 iOS host app을 설정한다. +- 비공개 Firebase plist를 git 추적 제외 경로에 배치한다. +- APNs 등록, token handoff, notification open routing을 구현하거나 검증한다. +- 승인된 발송 경로로 smoke를 실행하거나 실행을 조율한다. +- 민감값을 제거한 증거를 task 기록 또는 비공개 실행 메모에 남긴다. -## Current Repo Note +## 현재 저장소 상태 -The iOS plugin has a minimum debug/action bridge, but real APNs/FCM smoke still -needs the private Apple/Firebase/device setup above plus native APNs/token/open -routing work. +iOS plugin에는 최소한의 debug/action bridge가 있지만, 실제 APNs/FCM smoke를 수행하려면 위의 Apple/Firebase/기기 설정과 native APNs, token, open routing 작업이 추가로 필요하다. diff --git a/docs/linux-notification-test-guide.md b/docs/linux-notification-test-guide.md index fa47acad..63a9fc03 100644 --- a/docs/linux-notification-test-guide.md +++ b/docs/linux-notification-test-guide.md @@ -1,38 +1,34 @@ -# Linux Notification Environment Preparation +# Linux 알림 환경 준비 가이드 -Last verified: 2026-06-02 +마지막 확인일: 2026-06-02 -Read this when you need to provide Linux runner and desktop notification -environment choices so an agent can finish Linux notification implementation and -smoke verification. You do not need to run the test from this document. +에이전트가 Linux 알림 구현과 smoke 검증을 마무리하려면 Linux runner와 데스크톱 알림 환경 선택이 필요하다. 이 문서는 사용자가 무엇을 준비해야 하는지 정리한 가이드이며, 사용자가 직접 이 문서만 보고 테스트를 실행할 필요는 없다. -## Provide +## 준비할 항목 -| Needed | What to prepare | +| 항목 | 준비 내용 | |---|---| -| Linux runner | Local machine, VM, remote desktop, headless-only runner, or deferral. | -| Distribution | Distribution and version, such as Ubuntu, Debian, or Fedora. | -| Desktop session | GNOME/KDE/XFCE/other and X11/Wayland/headless. | -| Notification path | D-Bus notifications, XDG Desktop Portal, libnotify, or debug injection only. | -| Dependencies | Whether the agent may install required system packages. | -| Operator path | Who handles UI prompts/clicks if the runner is remote. | -| Evidence path | Choose where sanitized logs/screenshots/run notes should be stored. | +| Linux runner | 로컬 장비, VM, remote desktop, headless 전용 runner 중 하나를 정하거나 visible smoke 보류 여부를 정한다. | +| 배포판 | Ubuntu, Debian, Fedora 등 배포판과 버전을 정한다. | +| 데스크톱 세션 | GNOME/KDE/XFCE/기타 환경과 X11/Wayland/headless 여부를 정한다. | +| 알림 경로 | D-Bus notifications, XDG Desktop Portal, libnotify, debug injection 전용 중 하나를 선택한다. | +| 의존성 | 에이전트가 필요한 system package를 설치해도 되는지 정한다. | +| 조작 책임 | runner가 원격이면 UI prompt/click을 누가 처리할지 정한다. | +| 증거 위치 | 민감값을 제거한 로그, 스크린샷, 실행 메모를 어디에 남길지 정한다. | -## Do Not Put In Tracked Files +## tracked 파일에 넣지 말아야 할 값 -- Private host names, user names, private endpoints, auth tokens, channel names, - server URLs, machine-identifying session details, private package repository - credentials, device tokens, or signing keys. +- 비공개 host name, user name, private endpoint, auth token, channel name, server URL +- 장비를 식별할 수 있는 session detail, private package repository credential, device token, signing key -## Agent Can Then +## 준비 후 에이전트가 할 수 있는 일 -- add Linux platform registration and host scaffold if selected; -- implement the native notification/action bridge; -- configure the selected desktop notification path; -- run routing checks and, if allowed, visible notification smoke; -- record sanitized evidence in the task or private run note. +- 선택된 범위에 따라 Linux platform registration과 host scaffold를 추가한다. +- native notification/action bridge를 구현한다. +- 선택된 desktop notification path를 설정한다. +- routing check를 실행하고, 허용된 경우 visible notification smoke를 수행한다. +- 민감값을 제거한 증거를 task 기록 또는 비공개 실행 메모에 남긴다. -## Current Repo Note +## 현재 저장소 상태 -Linux is not registered yet and has no plugin or test-host scaffold. Smoke work -first needs platform scaffold plus the environment choices above. +Linux는 아직 등록되지 않았고 plugin 또는 test-host scaffold도 없다. Smoke 작업을 시작하려면 먼저 platform scaffold와 위의 환경 선택이 필요하다. diff --git a/docs/macos-notification-test-guide.md b/docs/macos-notification-test-guide.md index 212cb37f..d9b4f71b 100644 --- a/docs/macos-notification-test-guide.md +++ b/docs/macos-notification-test-guide.md @@ -1,38 +1,33 @@ -# macOS Notification Access Preparation +# macOS 알림 접근 준비 가이드 -Last verified: 2026-06-02 +마지막 확인일: 2026-06-02 -Read this when you need to provide macOS runner/signing access so an agent can -finish macOS notification implementation and smoke verification. You do not need -to run the test from this document. +에이전트가 macOS 알림 구현과 smoke 검증을 마무리하려면 macOS runner와 signing 접근 방식이 필요하다. 이 문서는 사용자가 무엇을 준비해야 하는지 정리한 가이드이며, 사용자가 직접 이 문서만 보고 테스트를 실행할 필요는 없다. -## Provide +## 준비할 항목 -| Needed | What to prepare | +| 항목 | 준비 내용 | |---|---| -| macOS runner | Local Mac, remote Mac, or a decision that visible smoke is deferred. | -| Operator path | Who handles UI prompts if the runner is remote. | -| Signing mode | Local ad hoc, Apple Developer signing, or distribution/notarization path. | -| Bundle ID | Required if signing beyond ad hoc is needed. | -| Apple access | Team/provisioning access if notification entitlement or APNs is in scope. | -| Push scope | Decide local notification only, APNs/Firebase-backed smoke, or deferred push. | -| Evidence path | Choose where sanitized logs/screenshots/run notes should be stored. | +| macOS runner | 로컬 Mac, 원격 Mac 중 하나를 정하거나 visible smoke 보류 여부를 정한다. | +| 조작 책임 | runner가 원격이면 UI prompt를 누가 처리할지 정한다. | +| Signing mode | local ad hoc, Apple Developer signing, distribution/notarization path 중 하나를 선택한다. | +| Bundle ID | ad hoc을 넘는 signing이 필요하면 Bundle ID를 준비한다. | +| Apple 접근 | notification entitlement 또는 APNs가 범위에 있으면 Team/provisioning 접근 방식을 정한다. | +| Push 범위 | local notification만 검증할지, APNs/Firebase 기반 smoke까지 할지, push를 보류할지 정한다. | +| 증거 위치 | 민감값을 제거한 로그, 스크린샷, 실행 메모를 어디에 남길지 정한다. | -## Do Not Put In Tracked Files +## tracked 파일에 넣지 말아야 할 값 -- Team ID, signing identity, provisioning profile, notarization profile, Apple - ID, APNs/Firebase secrets, device token, private endpoint, auth token, channel - name, user name, or server URL. +- Team ID, signing identity, provisioning profile, notarization profile, Apple ID +- APNs/Firebase secret, device token, private endpoint, auth token, channel name, user name, server URL -## Agent Can Then +## 준비 후 에이전트가 할 수 있는 일 -- configure the macOS host app for the selected signing mode; -- implement or verify the native notification/action bridge; -- run local routing checks and, if allowed, visible notification smoke; -- record sanitized evidence in the task or private run note. +- 선택된 signing mode에 맞게 macOS host app을 설정한다. +- native notification/action bridge를 구현하거나 검증한다. +- local routing check를 실행하고, 허용된 경우 visible notification smoke를 수행한다. +- 민감값을 제거한 증거를 task 기록 또는 비공개 실행 메모에 남긴다. -## Current Repo Note +## 현재 저장소 상태 -The macOS plugin is still a scaffold. It currently has only the legacy -`nexo_messaging` channel, so visible notification smoke also needs bridge -implementation work. +macOS plugin은 아직 scaffold 상태다. 현재는 legacy `nexo_messaging` channel만 있으므로 visible notification smoke를 수행하려면 bridge 구현 작업도 필요하다. diff --git a/docs/runtime-image-validation.md b/docs/runtime-image-validation.md index 9d4bec3c..f6f0d9c0 100644 --- a/docs/runtime-image-validation.md +++ b/docs/runtime-image-validation.md @@ -1,21 +1,21 @@ -# Nexo Runtime Image Validation +# Nexo Runtime Image 검증 -This document records the registry, tag, architecture, and verification digests for nexo-owned runtime images. +이 문서는 nexo-owned runtime image의 registry, tag, architecture, verification digest를 기록한다. -## Published Images Summary +## 게시된 Image 요약 -| Service | Target Architecture | Immutable Tag | Latest Tag | Digest (Immutable Tag) | Digest (Latest) | +| 서비스 | 대상 Architecture | Immutable Tag | Latest Tag | Digest (Immutable Tag) | Digest (Latest) | |---|---|---|---|---|---| | **Core (Mattermost)** | `linux/arm64` | `v11.4.2-arm64` | `latest` | `sha256:a811233f0625dd72a43c4b2315010ad67355fccc34be3e29d44e7aaab202b3ee` | `sha256:a811233f0625dd72a43c4b2315010ad67355fccc34be3e29d44e7aaab202b3ee` | | **Push-Proxy** | `linux/arm64` | `v11.4.2-arm64` | `latest` | `sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdfe4c6fc70f10b0b` | `sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdfe4c6fc70f10b0b` | -## Verification Evidence +## 검증 증거 -### Registry API Manifest Headers -This section displays registry manifest verification logs, ensuring the matching `Docker-Content-Digest` is resolved. +### Registry API Manifest Header +이 섹션은 일치하는 `Docker-Content-Digest`가 해석되는지 확인한 registry manifest 검증 log를 보여준다. ```sh -# Fetch Core (Mattermost) manifests from registry +# registry에서 Core(Mattermost) manifest 조회 $ curl -fsSI -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://toki-labs.com:5050/v2/nexo/mattermost/manifests/latest HTTP/1.1 200 OK Server: nginx/1.29.3 @@ -24,7 +24,7 @@ Content-Length: 6766 Docker-Content-Digest: sha256:a811233f0625dd72a43c4b2315010ad67355fccc34be3e29d44e7aaab202b3ee Etag: "sha256:a811233f0625dd72a43c4b2315010ad67355fccc34be3e29d44e7aaab202b3ee" -# Fetch Push-Proxy manifests from registry +# registry에서 Push-Proxy manifest 조회 $ curl -fsSI -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://toki-labs.com:5050/v2/nexo/push-proxy/manifests/latest HTTP/1.1 200 OK Server: nginx/1.29.3 @@ -34,8 +34,8 @@ Docker-Content-Digest: sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdf Etag: "sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdfe4c6fc70f10b0b" ``` -### Remote Host Image Inspect (Architecture Proof) -This section lists concrete inspection output executed directly on the remote Mac build host (`toki@toki-labs.com`). +### Remote Host Image Inspect (Architecture 증거) +이 섹션은 remote Mac build host(`toki@toki-labs.com`)에서 직접 실행한 inspect output을 기록한다. ```sh $ ssh toki@toki-labs.com '/usr/local/bin/docker image inspect toki-labs.com:5050/nexo/mattermost:latest --format "{{.Os}}/{{.Architecture}} {{range .RepoDigests}}{{.}} {{end}}" && /usr/local/bin/docker image inspect toki-labs.com:5050/nexo/mattermost:v11.4.2-arm64 --format "{{.Os}}/{{.Architecture}} {{range .RepoDigests}}{{.}} {{end}}" && /usr/local/bin/docker image inspect toki-labs.com:5050/nexo/push-proxy:latest --format "{{.Os}}/{{.Architecture}} {{range .RepoDigests}}{{.}} {{end}}" && /usr/local/bin/docker image inspect toki-labs.com:5050/nexo/push-proxy:v11.4.2-arm64 --format "{{.Os}}/{{.Architecture}} {{range .RepoDigests}}{{.}} {{end}}"' @@ -46,11 +46,11 @@ linux/arm64 toki-labs.com:5050/nexo/push-proxy@sha256:73d104148e66bb24e901bd1787 linux/arm64 toki-labs.com:5050/nexo/push-proxy@sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdfe4c6fc70f10b0b ``` -### Remote Compose Smoke Evidence -This section contains the validation log of copying the local compose files to the remote development host, running a config check, pulling nexo-owned images, and performing service smoke tests. +### Remote Compose Smoke 증거 +이 섹션은 local compose file을 remote development host로 복사하고, config check를 실행하고, nexo-owned image를 pull한 뒤 service smoke test를 수행한 검증 log를 담는다. ```sh -# 1. Compare local and remote file hashes (Parity Verification) +# 1. local/remote file hash 비교(parity verification) $ sha256sum docker-compose.yml .env.example c46bc291e42b1e87ca5e6b49d118bb59c67b0b2b1412a2751c6089e49d492563 docker-compose.yml fa56a8dc7a8dddc7737d42ec048e4f29836252e277e2d270f0ad0e7cbb38d430 .env.example @@ -59,13 +59,13 @@ $ ssh toki@toki-labs.com 'cd ~/docker/agent-service/nexo/compose && sha256sum do c46bc291e42b1e87ca5e6b49d118bb59c67b0b2b1412a2751c6089e49d492563 docker-compose.yml fa56a8dc7a8dddc7737d42ec048e4f29836252e277e2d270f0ad0e7cbb38d430 .env.example -# 2. Check remote Docker Compose configuration +# 2. remote Docker Compose configuration 확인 $ ssh toki@toki-labs.com 'cd ~/docker/agent-service/nexo/compose && /usr/local/bin/docker compose --env-file .env.example config >/tmp/nexo-compose-config.yml && /usr/bin/grep -E "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64" /tmp/nexo-compose-config.yml' image: toki-labs.com:5050/nexo/mattermost:latest platform: linux/arm64 image: toki-labs.com:5050/nexo/push-proxy:latest -# 3. Pull and start services on the remote server +# 3. remote server에서 service pull 및 시작 $ ssh toki@toki-labs.com 'export PATH=$PATH:/Applications/Docker.app/Contents/Resources/bin && cd ~/docker/agent-service/nexo/compose && /usr/local/bin/docker compose pull && /usr/local/bin/docker compose up -d' Container nexo-core-db Running Container nexo-core-push-proxy Recreated @@ -74,7 +74,7 @@ Container nexo-core-push-proxy Started Container nexo-core-db Healthy Container nexo-core Started -# 4. Remote Runtime Smoke Checks +# 4. remote runtime smoke check $ ssh toki@toki-labs.com 'cd ~/docker/agent-service/nexo/compose && curl -fsS "http://localhost:18065/api/v4/system/ping" && /usr/local/bin/docker compose exec -T db pg_isready -U mmuser -d mattermost && curl -fsSI "http://localhost:18065" && /usr/local/bin/docker compose ps push-proxy' {"ActiveSearchBackend":"database","AndroidLatestVersion":"","AndroidMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"} /var/run/postgresql:5432 - accepting connections @@ -95,30 +95,30 @@ nexo-core-push-proxy toki-labs.com:5050/nexo/push-proxy:latest "/usr/local/b --- -## Current Repo Runtime and App Evidence +## 현재 Repo Runtime 및 App 증거 -This section presents the verification matrix for nexo local/remote runtime components and apps inside this repository. +이 섹션은 이 repository 안의 nexo local/remote runtime component와 app에 대한 검증 matrix를 보여준다. -| Target | Command / Manual Step | Environment | Expected Result | Actual Evidence | Status / Follow-up | +| 대상 | 명령 / 수동 단계 | 환경 | 기대 결과 | 실제 증거 | 상태 / 후속 조치 | |---|---|---|---|---|---| -| **Remote Runtime Smoke** | `ssh toki@toki-labs.com '...'` | Remote host (`toki-labs.com` Mac ARM64) | Active system ping returns `"status":"OK"`, docker compose services are healthy. | `{"status":"OK"}`, all containers (`core`, `db`, `push-proxy`) show Up and healthy on ports `18065`/`18066`. | **PASS** | -| **Unit & Widget Tests** | `bin/test` | Local workspace container | All tests in `packages/messaging_flutter` and `apps/flutter-test` pass successfully. | `All tests passed!` output from both Flutter plugin package and test app. | **PASS** | -| **Static Code Analysis** | `bin/lint` | Local workspace container | Both projects analyze cleanly with zero static issues or lint warnings. | `Analyzing messaging_flutter... No issues found!`, `Analyzing flutter-test... No issues found!`. | **PASS** | -| **Android Build Unit Tests** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/flutter-test/android && ./gradlew testDebugUnitTest'` | Remote host Android SDK (`emulator-5554`) | Gradle compiles and runs native unit tests for the Android host wrapper. | Remote Gradle test completed with `BUILD SUCCESSFUL in 22s`; `NexoMessagingPluginTest > onMethodCall_getPlatformVersion_returnsExpectedValue() PASSED`. | **PASS** | -| **Flutter Integration Test** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/flutter-test && flutter test && flutter test integration_test -d emulator-5554'` | Remote host Flutter + Android emulator (`emulator-5554`) | Integration test validates plugin debug event flow on connected device/emulator. | Widget tests passed (`4/4`), debug APK built/installed on `emulator-5554`, and integration suite completed with all `3` tests passing. | **PASS** | -| **Original Mattermost App** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/mattermost && npm run check-test'` | Remote host Node `22.22.3` / npm `10.9.8`, Ruby/watchman Mattermost workspace | ESLint + TypeScript check + Jest unit tests pass against the remote host baseline. | Korean `FormattedDate` snapshot baseline was updated from `AM` to remote `Intl.DateTimeFormat` output `오전`. Retry passed: `PASS app/components/formatted_date/index.test.tsx`; `Test Suites: 2 skipped, 612 passed, 612 of 614 total`; `Tests: 7 skipped, 8162 passed, 8169 total`; `Snapshots: 303 passed, 303 total`. | **PASS** | -| **Detox E2E Testing** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/mattermost && npm run e2e:android'` | Remote host Android emulator + Mattermost runtime | Detox builds and executes end-to-end user flows against the emulated app. | Firebase debug config was supplied as ignored local/remote `apps/mattermost/android/app/google-services.json` with matching `com.mattermost.rnbeta` client, and Gradle completed `assembleDebug assembleAndroidTest` with `BUILD SUCCESSFUL in 9m`. `.detoxrc.json` now defaults Android emulator runs to the remote host's `Pixel_6_Pro_API_34`. Detox auto-boot with `CI=true npm run e2e:android-test` starts qemu for `@Pixel_6_Pro_API_34`, but the auto-booted process did not attach to `adb devices` after about 5 minutes. Manual `Pixel_6_Pro_API_34` boot attaches as `emulator-5554`; with Metro and `adb reverse tcp:8081 tcp:8081`, a default-config smoke retry assigned `server_login.e2e.ts` to `emulator-5554 (Pixel_6_Pro_API_34)`, then failed in `beforeAll` app readiness with `Exceeded timeout of 180000 ms` and Detox multiple-interaction/app-disconnect errors. | **FAIL** — default AVD selection is fixed, but Android E2E still needs a stable boot/start procedure and app readiness/synchronization follow-up before login-flow PASS. | +| **Remote Runtime Smoke** | `ssh toki@toki-labs.com '...'` | Remote host(`toki-labs.com` Mac ARM64) | active system ping이 `"status":"OK"`를 반환하고 docker compose service가 healthy 상태다. | `{"status":"OK"}`, 모든 container(`core`, `db`, `push-proxy`)가 port `18065`/`18066`에서 Up/healthy 상태를 보였다. | **PASS** | +| **Unit & Widget Tests** | `bin/test` | Local workspace container | `packages/messaging_flutter`와 `apps/flutter-test`의 모든 test가 성공한다. | Flutter plugin package와 test app 모두 `All tests passed!` output을 남겼다. | **PASS** | +| **Static Code Analysis** | `bin/lint` | Local workspace container | 두 project 모두 static issue 또는 lint warning 없이 analyze된다. | `Analyzing messaging_flutter... No issues found!`, `Analyzing flutter-test... No issues found!`. | **PASS** | +| **Android Build Unit Tests** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/flutter-test/android && ./gradlew testDebugUnitTest'` | Remote host Android SDK(`emulator-5554`) | Gradle이 Android host wrapper의 native unit test를 compile하고 실행한다. | Remote Gradle test가 `BUILD SUCCESSFUL in 22s`로 완료되었고 `NexoMessagingPluginTest > onMethodCall_getPlatformVersion_returnsExpectedValue() PASSED`를 남겼다. | **PASS** | +| **Flutter Integration Test** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/flutter-test && flutter test && flutter test integration_test -d emulator-5554'` | Remote host Flutter + Android emulator(`emulator-5554`) | Integration test가 연결된 device/emulator에서 plugin debug event flow를 검증한다. | Widget test가 통과했고(`4/4`), debug APK가 `emulator-5554`에 build/install되었으며 integration suite의 모든 `3`개 test가 통과했다. | **PASS** | +| **Original Mattermost App** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/mattermost && npm run check-test'` | Remote host Node `22.22.3` / npm `10.9.8`, Ruby/watchman Mattermost workspace | ESLint + TypeScript check + Jest unit test가 remote host baseline에서 통과한다. | Korean `FormattedDate` snapshot baseline을 `AM`에서 remote `Intl.DateTimeFormat` output인 `오전`으로 갱신했다. Retry 결과: `PASS app/components/formatted_date/index.test.tsx`; `Test Suites: 2 skipped, 612 passed, 612 of 614 total`; `Tests: 7 skipped, 8162 passed, 8169 total`; `Snapshots: 303 passed, 303 total`. | **PASS** | +| **Detox E2E Testing** | `ssh toki@toki-labs.com 'cd ~/agent-work/nexo/apps/mattermost && npm run e2e:android'` | Remote host Android emulator + Mattermost runtime | Detox가 emulated app을 build하고 end-to-end user flow를 실행한다. | Firebase debug config는 matching `com.mattermost.rnbeta` client와 함께 ignored local/remote `apps/mattermost/android/app/google-services.json`로 제공되었고, Gradle은 `assembleDebug assembleAndroidTest`를 `BUILD SUCCESSFUL in 9m`로 완료했다. `.detoxrc.json`은 이제 Android emulator run을 remote host의 `Pixel_6_Pro_API_34`로 기본 설정한다. `CI=true npm run e2e:android-test`를 통한 Detox auto-boot는 `@Pixel_6_Pro_API_34`용 qemu를 시작하지만 약 5분 후에도 auto-booted process가 `adb devices`에 attach되지 않았다. 수동 `Pixel_6_Pro_API_34` boot는 `emulator-5554`로 attach된다. Metro와 `adb reverse tcp:8081 tcp:8081` 설정 후 default-config smoke retry에서 `server_login.e2e.ts`가 `emulator-5554 (Pixel_6_Pro_API_34)`에 배정되었지만, `beforeAll` app readiness에서 `Exceeded timeout of 180000 ms`와 Detox multiple-interaction/app-disconnect error로 실패했다. | **FAIL** — default AVD 선택은 수정되었지만, Android E2E는 login-flow PASS 전에 안정적인 boot/start 절차와 app readiness/synchronization 후속 작업이 필요하다. | --- -## Consumer Project Evidence +## Consumer Project 증거 -This section records the setup, integration status, and verification metrics for sibling/consumer projects. +이 섹션은 sibling/consumer project의 setup, integration status, verification metric을 기록한다. -| Target | Command / Manual Step | Environment | Expected Result | Actual Evidence | Status / Follow-up | +| 대상 | 명령 / 수동 단계 | 환경 | 기대 결과 | 실제 증거 | 상태 / 후속 조치 | |---|---|---|---|---|---| -| **`../nomadcode` Setup & Dependency** | File scanning for dependency references | Local workspace sibling | Local path dependency registered and mapped to `packages/messaging_flutter`. | `apps/client/pubspec.yaml` maps dependency `nexo_messaging` to path `../../../nexo/packages/messaging_flutter` (successfully generated/resolved in `.flutter-plugins-dependencies`, `pubspec.lock`). | **PASS** | -| **`../nomadcode` Test & Smoke** | `../nomadcode/bin/test` | Local workspace sibling | Core Go test suite and Client Flutter tests pass cleanly (includes push host integration). | All Go module tests (`cmd/plane-smoke`, `internal/adapters/*`, etc.) and all Flutter widget tests pass successfully. | **PASS** | -| **`../nomadcode` Android Smoke** | Remote Android notification smoke | Remote Android emulator env | Real FCM credential loads, push notification arrives, and ACK is verified. | Confirmed and archived in task `mattermost-messaging-android-smoke` on 2026-05-26/27. | **PASS** | -| **`../iop` Setup & Test** | `cd ../iop/apps/portal && flutter test` | Local workspace sibling | Verify integration of messaging plugin and code stability. | Compiling tests failed due to upstream `protobuf` package version mismatch in the shared `proto-socket` module. No `nexo_messaging` dependency is integrated yet. | **SKIP** (upstream protobuf compilation mismatch; no nexo integration yet) | -| **`../alt` Setup & Test** | `../alt/bin/test` | Local workspace sibling | Verify integration of messaging plugin and code stability. | `All tests passed!` output from ALT Go server components and Flutter widget tests. No `nexo_messaging` dependency is integrated yet. | **PASS** (clean baseline; no nexo integration yet) | +| **`../nomadcode` Setup & Dependency** | dependency reference file scanning | Local workspace sibling | local path dependency가 등록되고 `packages/messaging_flutter`에 mapping된다. | `apps/client/pubspec.yaml`이 dependency `nexo_messaging`을 path `../../../nexo/packages/messaging_flutter`로 mapping한다(`.flutter-plugins-dependencies`, `pubspec.lock`에서 성공적으로 generated/resolved). | **PASS** | +| **`../nomadcode` Test & Smoke** | `../nomadcode/bin/test` | Local workspace sibling | Core Go test suite와 Client Flutter test가 깨끗하게 통과한다(push host integration 포함). | 모든 Go module test(`cmd/plane-smoke`, `internal/adapters/*` 등)와 모든 Flutter widget test가 성공했다. | **PASS** | +| **`../nomadcode` Android Smoke** | Remote Android notification smoke | Remote Android emulator env | 실제 FCM credential이 load되고, push notification이 도착하며, ACK가 검증된다. | 2026-05-26/27에 task `mattermost-messaging-android-smoke`에서 확인 및 archive되었다. | **PASS** | +| **`../iop` Setup & Test** | `cd ../iop/apps/portal && flutter test` | Local workspace sibling | messaging plugin integration과 code stability를 확인한다. | shared `proto-socket` module의 upstream `protobuf` package version mismatch 때문에 test compile이 실패했다. 아직 `nexo_messaging` dependency는 통합되지 않았다. | **SKIP** (upstream protobuf compilation mismatch; 아직 nexo integration 없음) | +| **`../alt` Setup & Test** | `../alt/bin/test` | Local workspace sibling | messaging plugin integration과 code stability를 확인한다. | ALT Go server component와 Flutter widget test에서 `All tests passed!` output을 남겼다. 아직 `nexo_messaging` dependency는 통합되지 않았다. | **PASS** (clean baseline; 아직 nexo integration 없음) | diff --git a/docs/windows-notification-test-guide.md b/docs/windows-notification-test-guide.md index 81de2fa9..b92a0428 100644 --- a/docs/windows-notification-test-guide.md +++ b/docs/windows-notification-test-guide.md @@ -1,38 +1,34 @@ -# Windows Notification Environment Preparation +# Windows 알림 환경 준비 가이드 -Last verified: 2026-06-02 +마지막 확인일: 2026-06-02 -Read this when you need to provide Windows runner, packaging, and signing -choices so an agent can finish Windows notification implementation and smoke -verification. You do not need to run the test from this document. +에이전트가 Windows 알림 구현과 smoke 검증을 마무리하려면 Windows runner, packaging, signing 선택이 필요하다. 이 문서는 사용자가 무엇을 준비해야 하는지 정리한 가이드이며, 사용자가 직접 이 문서만 보고 테스트를 실행할 필요는 없다. -## Provide +## 준비할 항목 -| Needed | What to prepare | +| 항목 | 준비 내용 | |---|---| -| Windows runner | Local PC, VM, remote machine, or a decision that visible smoke is deferred. | -| Toolchain | Windows version plus Visual Studio/C++ desktop workload/Windows SDK availability. | -| Packaging mode | Unpackaged, MSIX, sparse package, or debug injection only. | -| Notification API | Windows App SDK, WinRT toast, desktop AppUserModelID fallback, or debug injection only. | -| Identity | Package identity or AppUserModelID if visible toast activation is in scope. | -| Signing | Test certificate, organization cert, Store association, or no signing. | -| Evidence path | Choose where sanitized logs/screenshots/run notes should be stored. | +| Windows runner | 로컬 PC, VM, 원격 장비 중 하나를 정하거나 visible smoke 보류 여부를 정한다. | +| Toolchain | Windows 버전과 Visual Studio/C++ desktop workload/Windows SDK 사용 가능 여부를 정한다. | +| Packaging mode | unpackaged, MSIX, sparse package, debug injection 전용 중 하나를 선택한다. | +| Notification API | Windows App SDK, WinRT toast, desktop AppUserModelID fallback, debug injection 전용 중 하나를 선택한다. | +| Identity | visible toast activation이 범위에 있으면 package identity 또는 AppUserModelID를 정한다. | +| Signing | test certificate, organization cert, Store association, signing 없음 중 하나를 선택한다. | +| 증거 위치 | 민감값을 제거한 로그, 스크린샷, 실행 메모를 어디에 남길지 정한다. | -## Do Not Put In Tracked Files +## tracked 파일에 넣지 말아야 할 값 -- Microsoft account values, package identity if private, signing certificate - contents/passwords, Store association files, push credentials, device token, - private endpoint, auth token, channel name, user name, or server URL. +- Microsoft 계정 값, 비공개 package identity, signing certificate 내용/password, Store association file +- push credential, device token, private endpoint, auth token, channel name, user name, server URL -## Agent Can Then +## 준비 후 에이전트가 할 수 있는 일 -- add Windows platform registration and host scaffold if selected; -- implement the native notification/action bridge; -- configure the selected notification API and packaging path; -- run routing checks and, if allowed, visible toast smoke; -- record sanitized evidence in the task or private run note. +- 선택된 범위에 따라 Windows platform registration과 host scaffold를 추가한다. +- native notification/action bridge를 구현한다. +- 선택된 notification API와 packaging path를 설정한다. +- routing check를 실행하고, 허용된 경우 visible toast smoke를 수행한다. +- 민감값을 제거한 증거를 task 기록 또는 비공개 실행 메모에 남긴다. -## Current Repo Note +## 현재 저장소 상태 -Windows is not registered yet and has no plugin or test-host scaffold. Smoke -work first needs platform scaffold plus the environment choices above. +Windows는 아직 등록되지 않았고 plugin 또는 test-host scaffold도 없다. Smoke 작업을 시작하려면 먼저 platform scaffold와 위의 환경 선택이 필요하다.