toki/nexo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: 업데이트된 문서 변경사항 적용

Browse source
This commit is contained in:
toki 2026-06-02 19:38:06 +09:00
parent e49fb45dcb
commit d18463ea80
6 changed files with 151 additions and 248 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

120
docs/README.md
View file

@ -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`는 그 내용을 반복하지 않고 문서 위치와 읽는 상황만 안내한다.

60
docs/ios-notification-test-guide.md
View file

@ -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 작업이 추가로 필요하다.

50
docs/linux-notification-test-guide.md
View file

@ -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와 위의 환경 선택이 필요하다.

49
docs/macos-notification-test-guide.md
View file

@ -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 구현 작업도 필요하다.

70
docs/runtime-image-validation.md
View file

@ -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 없음) |

50
docs/windows-notification-test-guide.md
View file

@ -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와 위의 환경 선택이 필요하다.