Add workspace operations docs

2026-06-07 10:28:02 +09:00 · 2026-06-07 10:28:02 +09:00 · a5f6d0e132
commit a5f6d0e132
parent be5f6d5522
4 changed files with 132 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -6,6 +6,10 @@
 !/.workspace-skills/
 !/.workspace-skills/**

+# Workspace-owned operations docs.
+!/workspace-ops/
+!/workspace-ops/**
+
 # Generated or local-only directories should stay ignored even if an allowed
 # directory is added later.
 /mattermost/
--- a/workspace-ops/environments.md
+++ b/workspace-ops/environments.md
@ -0,0 +1,33 @@
+# Workspace Environments
+
+이 문서는 하위 프로젝트의 local/test/runtime 환경을 workspace 관점에서 요약한다.
+상세 구현과 최종 source of truth는 각 프로젝트의 `agent-test/local/`, compose/env example, roadmap milestone에 둔다.
+
+## 공통 기준
+
+- tracked 문서에는 raw secret, token, password, private key, 계정 id를 쓰지 않는다.
+- ignored local file은 inventory 근거로만 보고, 값 자체를 복사하지 않는다.
+- 원격 runtime 포트 변경은 compose/env/smoke/client config 영향 확인 뒤 프로젝트별 마일스톤에서 처리한다.
+- host publish 표준화와 container 내부 listen 포트 변경은 별도 문제로 다룬다.
+
+## 프로젝트별 환경 요약
+
+| 프로젝트 | Local / Test 환경 | Remote / Runtime 환경 | 포트/환경 메모 |
+|---|---|---|---|
+| `alt` | Go workspace, Flutter client, local PostgreSQL/Redis compose, KIS smoke는 private testing env 의존 | `ssh toki@toki-labs.com`, `~/agent-work/alt` | API/worker 후보 `18030/18031`, frontend `13030`, optional wire `19030`, DB/cache `15430/16330`. KIS credential은 tracked 문서에 쓰지 않는다. |
+| `iop` | Docker compose 기반 Control Plane, Edge, Node, Client, PostgreSQL, Redis. work container 안 Docker-in-Docker는 피한다. | `ssh toki@toki-labs.com`, `/Users/toki/agent-work/iop` | workspace 기준 프로젝트. frontend `13000`, backend `18000`, artifact/model `18080/18081`, wire `19080/19081/19090`, metrics `19092`, DB/cache `15400/16300`. |
+| `nexo` | Mattermost core, webapp, push-proxy, Flutter test host, upstream dev compose | `ssh toki@toki-labs.com`, repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | core `18065`, push-proxy `18066`은 compatibility baseline. upstream dev compose 포트는 nexo-owned runtime 포트와 분리한다. |
+| `nomadcode` | Core local default `8080`, Docker compose DB/Redis, Flutter client, code-server preview | Android runner `$HOME/agent-work/nomadcode`, sibling `../nexo/packages/messaging_flutter`, `../proto-socket/dart` | frontend 후보 `13010`, backend 후보 `18010`, DB/cache `15410/16310`. Plane, Mattermost, Jira, IOP Edge endpoint는 secret 없이 책임 경계만 기록한다. |
+| `oto` | OTO Core local default `127.0.0.1:8080`, runner/local typed-command tests, Flutter client | 표준 remote runner 없음 | frontend 후보 `13020`, backend 후보 `18020`. `OTO_RUNNER_RELEASE_BASE_URL`은 HTTPS release URL 기준을 유지한다. |
+| `proto-socket` | same-language/cross-language test matrix, examples, per-language runners | Dart web/Chrome fallback: `ssh toki@toki-labs.com`, `~/agent-work/proto-socket-dart-web` | runtime 포트 없음. fixed crosstest local port `29090-29899`는 workspace 표준 예외. 예제 `9090`은 제품 host publish 포트로 보지 않는다. |
+| `agent-shell` | Dart/Flutter package test | 없음 | package 자체 포트 없음. |
+| `dart-app-core` | Dart library tests | 없음 | library 자체 포트 없음. |
+| `agentic-framework` | agent-ops framework/docs | 없음 | 서버/runtime 포트 없음. 포트 마일스톤 대상에서 제외한다. |
+
+## 변경 전 확인 항목
+
+- compose host publish 변경인지, container 내부 listen 변경인지 먼저 구분한다.
+- remote runner, code-server proxy, Android/Detox/Flutter Web smoke가 같은 포트를 참조하는지 확인한다.
+- README, `.env.example`, `agent-test/local/*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다.
+- DB/Redis host publish 변경은 로컬 도구와 외부 접속 필요 여부를 확인한 뒤 진행한다.
+- field runtime에서 이미 쓰는 `18080`, `18081`, `19080`, `19090`, `18065`, `18066`은 먼저 compatibility baseline으로 취급한다.
--- a/workspace-ops/ports.md
+++ b/workspace-ops/ports.md
@ -0,0 +1,55 @@
+# Workspace Ports
+
+이 문서는 workspace 하위 프로젝트의 host publish port, dev preview port, wire port, test runner port를 한눈에 보기 위한 운영 표다.
+컨테이너 내부 포트와 제품 기본 listen 포트는 가능한 유지하고, workspace 표준화 대상은 host publish, preview, remote runner 문서, smoke command로 둔다.
+
+## 원칙
+
+- 컨테이너 내부 포트는 각 제품/프레임워크의 표준값을 우선 유지한다.
+- 외부 검증이나 원격 runner에서 이미 쓰는 포트는 바로 바꾸지 않고 프로젝트별 마일스톤에서 영향 범위를 확인한다.
+- DB/Redis는 Docker network DNS를 우선하고, host publish가 필요한 경우에만 project offset 포트를 둔다.
+- secret, token, password, private endpoint 원문은 tracked 문서에 쓰지 않는다.
+- runtime service port가 없는 package는 포트 표준화 대상에서 제외한다.
+- `proto-socket`처럼 운영 서버가 아니라 test runner가 고정 포트를 쓰는 경우는 예외 대역으로 문서화한다.
+
+## 권장 대역
+
+| 용도 | 대역 | 설명 |
+|---|---:|---|
+| Frontend / Web preview | `13000-13099` | Flutter Web, static preview, code-server proxy host port |
+| Backend HTTP/API | `18000-18079` | 제품 API, core server, app backend host publish |
+| Artifact/bootstrap/model HTTP | `18080-18099` | artifact server, bootstrap, Edge OpenAI-compatible, A2A HTTP |
+| Wire / agent transport | `19000-19099` | proto-socket, Control Plane wire, Edge-Node TCP |
+| Metrics / diagnostics | `19100-19199` | metrics, diagnostic HTTP/TCP. 기존 `1909x`는 migration 전까지 허용 |
+| DB host publish | `15400-15499` | PostgreSQL host publish가 반드시 필요한 경우 |
+| Cache host publish | `16300-16399` | Redis host publish가 반드시 필요한 경우 |
+
+## 프로젝트별 슬롯
+
+| 프로젝트 | Frontend / Preview | Backend / API | Artifact / Model | Wire / Agent Transport | Metrics | DB / Cache | 메모 |
+|---|---:|---:|---:|---:|---:|---:|---|
+| `iop` | `13000` | `18000` | `18080`, `18081` | `19080`, `19081`, `19090` | `19092` | `15400`, `16300` | 기존 field 포트 `18080`, `18081`, `19080`, `19090` 유지/변경 검토 |
+| `nomadcode` | `13010` | `18010` | - | IOP 경유 | - | `15410`, `16310` | 기존 local core/default `8080` compatibility note 필요 |
+| `oto` | `13020` | `18020` | - | - | - | - | 기존 local default `127.0.0.1:8080` compatibility note 필요 |
+| `alt` | `13030` | `18030`, `18031` | - | `19030` optional | - | `15430`, `16330` | 기존 API/worker 포트와 migration note 필요 |
+| `nexo` | `13040` | `18065`, `18066` 유지 | - | - | - | compose-internal 우선 | 변경 필요 시 `18040` 계열 후보. `18065/18066`은 compatibility baseline |
+| `proto-socket` | - | - | - | test runner `29090-29899` | - | - | 운영 포트가 아니라 crosstest local fixed port 예외 |
+
+## 제외 또는 host 의존
+
+| 프로젝트 | 상태 | 메모 |
+|---|---|---|
+| `agent-shell` | 제외 | package 자체 포트 없음. host 앱이 환경을 소유한다. |
+| `dart-app-core` | 제외 | library 자체 포트 없음. |
+| `agentic-framework` | 제외 | 서버/runtime 포트 없음. 공통 agent-ops 문서 repo로만 본다. |
+
+## 관련 마일스톤
+
+| 프로젝트 | 마일스톤 |
+|---|---|
+| `alt` | `agent-roadmap/phase/trading-expansion/milestones/workspace-port-env-standardization.md` |
+| `iop` | `agent-roadmap/phase/automation-runtime-bridge/milestones/workspace-port-env-standardization.md` |
+| `nexo` | `agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md` |
+| `nomadcode` | `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md` |
+| `oto` | `agent-roadmap/phase/independent-control-plane/milestones/workspace-port-env-standardization.md` |
+| `proto-socket` | `agent-roadmap/milestones/workspace-port-env-standardization.md` |
--- a/workspace-ops/remote-runners.md
+++ b/workspace-ops/remote-runners.md
@ -0,0 +1,40 @@
+# Workspace Remote Runners
+
+이 문서는 workspace 하위 프로젝트에서 확인된 원격 runner, remote runtime path, field endpoint 성격을 정리한다.
+접속 credential, token, private key, secret 값은 기록하지 않는다.
+
+## 원격 runner 표
+
+| 프로젝트 | 접속/호스트 | 원격 경로 | 용도 | 메모 |
+|---|---|---|---|---|
+| `alt` | `ssh toki@toki-labs.com` | `~/agent-work/alt` | ALT 테스트/원격 작업 runner | KIS live smoke와 private testing env 값은 tracked 문서에 쓰지 않는다. |
+| `iop` | `ssh toki@toki-labs.com` | `/Users/toki/agent-work/iop` | Control Plane/Edge/Node/Client remote validation | Docker-in-Docker 없이 remote host/runtime 기준으로 검증한다. |
+| `nexo` | `ssh toki@toki-labs.com` | repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | Mattermost core/push-proxy runtime validation | core `18065`, push-proxy `18066`은 compatibility baseline으로 둔다. |
+| `nomadcode` | remote Android runner host | `$HOME/agent-work/nomadcode` | Flutter/Android runner, sibling package integration | `../nexo/packages/messaging_flutter`, `../proto-socket/dart` sibling dependency를 전제로 한다. |
+| `proto-socket` | `ssh toki@toki-labs.com` | `~/agent-work/proto-socket-dart-web` | Dart web/Chrome fallback, WSS/SPKI wrapper | runtime service가 아니라 test harness 예외다. |
+| `oto` | 없음 | 없음 | local runner 중심 | 표준 remote runner가 확인되면 이 문서에 추가한다. |
+
+## Remote / Field 포트 기준
+
+| 프로젝트 | 포트/URL 성격 | 값 |
+|---|---|---|
+| `iop` | artifact/bootstrap HTTP | `18080` |
+| `iop` | Edge OpenAI-compatible HTTP | `18081` |
+| `iop` | Control Plane wire | `19080` |
+| `iop` | Edge-Node / Edge runtime TCP | `19090` |
+| `iop` | metrics 기존 field 계열 | `19092` |
+| `alt` | field frontend/dev preview reserve | `13000-13099` |
+| `alt` | field artifact/bootstrap | `18080` |
+| `alt` | field Edge OpenAI-compatible | `18081` |
+| `alt` | field CP wire / Edge runtime | `19080`, `19090` |
+| `alt` | field metrics / specialized reserve | `19092`, `19190` |
+| `nexo` | external core HTTP | `18065` |
+| `nexo` | push-proxy HTTP | `18066` |
+| `proto-socket` | crosstest local fixed port range | `29090-29899` |
+
+## 운영 메모
+
+- 원격 포트는 문서 정리만으로 바꾸지 않는다. 변경 전에는 해당 프로젝트 마일스톤에서 smoke, client config, remote runner path를 같이 확인한다.
+- field/runtime 포트와 local development 후보 포트가 다를 수 있다. 이 경우 field 포트를 compatibility baseline으로 먼저 둔다.
+- `proto-socket`의 remote runner는 제품 runtime이 아니라 Dart web/Chrome test harness 보조 경로다.
+- private host 값은 이미 공개된 host 별칭 수준만 기록하고, credential이나 token은 기록하지 않는다.