From 1a90b7fe095883881776cfd1f8774066e36196ed Mon Sep 17 00:00:00 2001 From: toki Date: Fri, 12 Jun 2026 19:07:04 +0900 Subject: [PATCH] add agent-test dev smoke tests and update config files --- .env.dev.example | 20 +++++ AGENTS.md | 1 + CLAUDE.md | 1 + GEMINI.md | 1 + Makefile | 6 +- agent-test/dev/client-smoke.md | 98 ++++++++++++++++++++++ agent-test/dev/control-plane-smoke.md | 95 +++++++++++++++++++++ agent-test/dev/edge-smoke.md | 100 ++++++++++++++++++++++ agent-test/dev/node-smoke.md | 100 ++++++++++++++++++++++ agent-test/dev/platform-common-smoke.md | 92 +++++++++++++++++++++ agent-test/dev/rules.md | 67 +++++++++++++++ agent-test/dev/testing-smoke.md | 105 ++++++++++++++++++++++++ docker-compose.yml | 2 +- 13 files changed, 685 insertions(+), 3 deletions(-) create mode 100644 .env.dev.example create mode 100644 agent-test/dev/client-smoke.md create mode 100644 agent-test/dev/control-plane-smoke.md create mode 100644 agent-test/dev/edge-smoke.md create mode 100644 agent-test/dev/node-smoke.md create mode 100644 agent-test/dev/platform-common-smoke.md create mode 100644 agent-test/dev/rules.md create mode 100644 agent-test/dev/testing-smoke.md diff --git a/.env.dev.example b/.env.dev.example new file mode 100644 index 0000000..7f67683 --- /dev/null +++ b/.env.dev.example @@ -0,0 +1,20 @@ +COMPOSE_PROJECT_NAME=iop-dev-agent +IOP_COMPOSE_NETWORK=iop-dev-agent-net + +IOP_CONTROL_PLANE_HTTP_PORT=18001 +IOP_CONTROL_PLANE_WIRE_PORT=19001 +IOP_CONTROL_PLANE_EDGE_WIRE_PORT=19002 +IOP_EDGE_NODE_PORT=19003 +IOP_WEB_PORT=13001 + +IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 +IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client + +IOP_POSTGRES_USER=iop +IOP_POSTGRES_PASSWORD=iop_dev_password +IOP_POSTGRES_DB=iop-control-plane-dev-agent +IOP_POSTGRES_PORT=15401 + +IOP_REDIS_PORT=16301 +IOP_REDIS_DB=3 +IOP_REDIS_KEY_PREFIX=iop:control-plane:dev-agent: diff --git a/AGENTS.md b/AGENTS.md index d0488a8..9b263b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,3 +42,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev: `agent-test/dev/rules.md` (없으면 `create-test`) diff --git a/CLAUDE.md b/CLAUDE.md index d0488a8..9b263b8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,3 +42,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev: `agent-test/dev/rules.md` (없으면 `create-test`) diff --git a/GEMINI.md b/GEMINI.md index d0488a8..9b263b8 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -42,3 +42,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev: `agent-test/dev/rules.md` (없으면 `create-test`) diff --git a/Makefile b/Makefile index 7c3d056..4292489 100644 --- a/Makefile +++ b/Makefile @@ -18,6 +18,8 @@ NODE_TARGETS ?= linux-arm64 linux-amd64 darwin-arm64 darwin-amd64 windows-arm64 NODE_TARGET_PARTS = $(subst -, ,$(NODE_TARGET)) NODE_GOOS = $(word 1,$(NODE_TARGET_PARTS)) NODE_GOARCH = $(word 2,$(NODE_TARGET_PARTS)) +IOP_CONTROL_PLANE_HTTP_URL ?= http://localhost:18000 +IOP_CONTROL_PLANE_WIRE_URL ?= ws://localhost:19080/client all: build @@ -128,8 +130,8 @@ client-test: client-build-web: cd apps/client && flutter build web \ - --dart-define=IOP_CONTROL_PLANE_HTTP_URL=http://localhost:18000 \ - --dart-define=IOP_CONTROL_PLANE_WIRE_URL=ws://localhost:19080/client + --dart-define=IOP_CONTROL_PLANE_HTTP_URL=$(IOP_CONTROL_PLANE_HTTP_URL) \ + --dart-define=IOP_CONTROL_PLANE_WIRE_URL=$(IOP_CONTROL_PLANE_WIRE_URL) clean: rm -rf build diff --git a/agent-test/dev/client-smoke.md b/agent-test/dev/client-smoke.md new file mode 100644 index 0000000..014e7aa --- /dev/null +++ b/agent-test/dev/client-smoke.md @@ -0,0 +1,98 @@ +--- +test_env: dev +test_profile: client-smoke +domain: client +verification_type: smoke +last_rule_updated_at: 2026-06-12 +--- + +# client-smoke dev 테스트 + +## 읽기 조건 + +- `apps/client/**` 또는 `packages/flutter/iop_console/**` 변경의 dev 테스트, 검증, 실행 조건 판단이 필요한 경우 + +## 적용 범위 + +- IOP Flutter client app shell +- IOP-owned embeddable console package +- Client-Control Plane proto-socket hello baseline +- Flutter widget/unit tests +- dev web preview와 compose web build URL 주입 + +## 분류 + +- domain: client +- verification_type: smoke +- scope: Flutter client와 IOP console package 변경 + +## 환경 + +- host: Flutter client 또는 `packages/flutter/iop_console`가 포함된 runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다. +- port: web/dev preview `13001`, Control Plane HTTP `18001`, Portal/Control Plane wire test endpoint `19001`, Edge-Node TCP transport `19003`. +- runtime: Flutter/Dart +- package manager: Flutter pub +- docker: compose 검증은 `docker compose --env-file .env.dev.example ...` 기준이다. +- external service: sibling path dependencies `../agent-shell`, `../nexo/packages/messaging_flutter`, `../proto-socket/dart` +- model endpoint: +- credential: token/secret 원문은 문서에 기록하지 않는다. + +명령은 원격 runner 사용 시 `/Users/toki/agent-work/iop-dev` 기준으로 실행한다. 현재 작업 컨테이너의 변경분이 원격 checkout에 동기화되지 않았으면 원격 검증 완료로 보지 않는다. + +## 명령 + +- setup: `cd apps/client && flutter pub get` +- package-setup: `cd packages/flutter/iop_console && flutter pub get` +- unit: `cd apps/client && flutter test` +- package-unit: `cd packages/flutter/iop_console && flutter test` +- lint: `cd apps/client && flutter analyze --no-fatal-infos` +- smoke: `cd apps/client && flutter test` +- e2e: `IOP_WEB_PORT=13001 IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client ./scripts/dev/web.sh` +- compose-e2e: `IOP_EDGE_NODE_TOKEN= docker compose --env-file .env.dev.example up --build` +- web-build: `make client-build-web IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client` +- model: +- full-cycle: + +## 필수 검증 + +- client 또는 `packages/flutter/iop_console` 변경은 최소 `cd apps/client && flutter test`로 확인한다. +- `packages/flutter/iop_console` 자체 API나 widget 구조가 바뀌면 `cd packages/flutter/iop_console && flutter test` 실행 가능 여부를 확인한다. +- analyzer 영향이 있는 dependency, app shell, generated import 변경이면 `cd apps/client && flutter analyze --no-fatal-infos`를 함께 확인한다. +- Web build/deploy, `apps/client/Dockerfile`, `docker-compose.yml`, `scripts/dev/web.sh`, `Makefile client-build-web` 변경은 원격 runner에서 dev-server 기동 또는 compose build 중 변경 범위에 맞는 경로를 확인하고, 외부 브라우저 확인 URL이 `http://toki-labs.com:13001` 계열인지 보고한다. +- compose 경로를 확인할 때는 `IOP_EDGE_NODE_TOKEN`을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다. + +## 보조 검증 + +- `cd apps/client && flutter pub get` +- `cd packages/flutter/iop_console && flutter pub get` + +## 판정 기준 + +- Flutter test가 실패 없이 종료한다. +- Analyzer는 기존 non-fatal info를 기능 실패로 확대하지 않는다. +- path dependency가 없어 실행하지 못하면 누락된 sibling workspace를 차단 사유로 보고한다. +- dev web preview가 필요한 경우 browser-facing URL과 compiled Control Plane HTTP/WS URL이 모두 dev 포트(`13001`, `18001`, `19001`)를 사용한다. + +## 기준 출력 예시 + +```text +All tests passed! +``` + +## 차단 기준 + +- 원격 runner 접근, Flutter SDK, Docker compose, 또는 필요한 dev 포트 개방이 없어 client runtime 검증을 실행할 수 없다. +- 필요한 sibling path dependency가 없어 `flutter pub get` 또는 test가 진행되지 않는다. + +## 보고 항목 + +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다. +- IOP client에 NomadCode product shell UX를 직접 복제하지 않는다. diff --git a/agent-test/dev/control-plane-smoke.md b/agent-test/dev/control-plane-smoke.md new file mode 100644 index 0000000..cecd2a4 --- /dev/null +++ b/agent-test/dev/control-plane-smoke.md @@ -0,0 +1,95 @@ +--- +test_env: dev +test_profile: control-plane-smoke +domain: control-plane +verification_type: smoke +last_rule_updated_at: 2026-06-12 +--- + +# control-plane-smoke dev 테스트 + +## 읽기 조건 + +- `apps/control-plane/**` 변경 또는 Control Plane health/readiness, config loading, wire endpoint dev 검증 판단이 필요한 경우 + +## 적용 범위 + +- `apps/control-plane/cmd/control-plane/**` +- `apps/control-plane/internal/wire/**` +- `apps/control-plane/Dockerfile` +- Control Plane HTTP health/readiness와 proto-socket WebSocket hello baseline +- Control Plane-Edge TCP wire endpoint, Edge outbound hello, disconnect baseline +- dev compose host publish와 DB/Redis 분리 + +## 분류 + +- domain: control-plane +- verification_type: smoke +- scope: control-plane HTTP와 wire baseline + +## 환경 + +- host: Docker compose 또는 Flutter client가 포함된 runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다. +- port: Control Plane HTTP `18001` (host-facing), Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, web/dev preview `13001`. +- runtime: Go `1.24`, Docker compose +- package manager: Go modules / Makefile +- docker: `docker-compose.yml`에 postgres, redis, control-plane, edge, web service가 정의되어 있다. dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다. +- external service: postgres host publish `15401`, redis host publish `16301` +- model endpoint: +- credential: DB/Redis credential 원문은 문서에 기록하지 않는다. + +## 명령 + +- setup: `IOP_EDGE_NODE_TOKEN= docker compose --env-file .env.dev.example up -d postgres redis control-plane edge web` +- lint: +- unit: `go test ./apps/control-plane/...` +- smoke: `curl -fsS http://127.0.0.1:18001/healthz`, `curl -fsS http://127.0.0.1:18001/readyz` +- e2e: `make test-control-plane-edge-wire`는 보조 smoke이며 기본 포트를 쓰는 스크립트이므로 dev 포트 override 가능 여부를 먼저 확인한다. +- model: +- full-cycle: Control Plane command, health/readiness, wire hello 수동 검증 + +## 필수 검증 + +- 변경한 control-plane 패키지 또는 `go test ./apps/control-plane/...`를 실행한다. +- HTTP lifecycle 변경 시 dev port `/healthz`와 `/readyz`를 확인한다. +- Client-Control Plane wire protocol 변경 시 proto-socket WebSocket hello baseline을 dev wire port `19001` 기준으로 확인한다. +- Control Plane-Edge TCP wire, Edge outbound connector, registry lifecycle 변경 시 dev `19002` 기준으로 hello accepted, Edge connected, Edge disconnected marker를 확인한다. + +## 보조 검증 + +- docker compose control-plane service healthcheck를 확인한다. +- Edge 포함 compose 검증에서는 `IOP_EDGE_NODE_TOKEN`을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다. + +## 판정 기준 + +- control-plane service가 dev stack으로 기동되고 health endpoint가 성공 응답을 반환한다. +- wire endpoint는 Control Plane 브라우저/앱 경계로 유지되고 Node 직접 연결/스케줄링 경로로 확장되지 않는다. +- dev stack은 local/test stack의 host publish 포트(`13000`, `18000`, `19080`, `19081`, `15400`, `16300`)를 점유하지 않는다. + +## 기준 출력 예시 + +```text +curl -fsS http://127.0.0.1:18001/healthz +curl -fsS http://127.0.0.1:18001/readyz +``` + +## 차단 기준 + +- docker compose 실행 권한 또는 postgres/redis service 기동이 불가능하다. +- 현재 작업 컨테이너에서 Docker-in-Docker가 필요해지는 검증은 수행하지 않고 원격 runner 차단으로 보고한다. +- 실제 DB/Redis credential 확인이 필요한데 안전하게 제공되지 않았다. +- dev 포트가 이미 점유되어 있어 local/test stack과 공존할 수 없다. + +## 보고 항목 + +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- Control Plane에서 Node 직접 연결이나 직접 스케줄링을 제품 기본 계약으로 만들지 않는다. +- 실제 DB/Redis credential이나 private endpoint를 tracked docs/rules에 기록하지 않는다. +- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다. diff --git a/agent-test/dev/edge-smoke.md b/agent-test/dev/edge-smoke.md new file mode 100644 index 0000000..c790e5d --- /dev/null +++ b/agent-test/dev/edge-smoke.md @@ -0,0 +1,100 @@ +--- +test_env: dev +test_profile: edge-smoke +domain: edge +verification_type: smoke +last_rule_updated_at: 2026-06-12 +--- + +# edge-smoke dev 테스트 + +## 읽기 조건 + +- `apps/edge/**` 변경 또는 edge registry, transport, service, console, OpenAI-compatible/A2A 입력 표면 dev 검증 판단이 필요한 경우 + +## 적용 범위 + +- `apps/edge/cmd/edge/**` +- `apps/edge/internal/bootstrap/**` +- `apps/edge/internal/transport/**` +- `apps/edge/internal/service/**` +- `apps/edge/internal/events/**` +- `apps/edge/internal/input/**` +- `apps/edge/internal/openai/**` +- `apps/edge/internal/opsconsole/**` +- `apps/edge/internal/node/**` + +## 분류 + +- domain: edge +- verification_type: smoke +- scope: edge 실행 그룹, node registry, input surface baseline + +## 환경 + +- host: local checkout. dev runtime, external CLI, shared port evidence가 필요하면 원격 runner를 사용한다. +- port: compose Edge-Node TCP transport `19003`; dev artifact/bootstrap HTTP 후보 `18082`, dev Edge OpenAI-compatible HTTP 후보 `18083`, dev Edge metrics 후보 `19101`. +- runtime: Go `1.24` +- package manager: Go modules / Makefile +- docker: unit/smoke quick check는 Docker를 요구하지 않는다. compose dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다. +- external service: dev artifact/base URL 후보 `http://toki-labs.com:18082`, dev Edge runtime 주소 후보 `toki-labs.com:19003` +- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1` +- credential: token/secret 원문은 문서에 기록하지 않는다. + +## 명령 + +- setup: +- lint: +- unit: `go test ./apps/edge/...` +- smoke: `./scripts/e2e-smoke.sh`는 기본 포트 임시 설정을 쓰는 보조 smoke이므로 dev 포트 override 필요 여부를 먼저 확인한다. +- e2e: `make test-e2e`는 보조 smoke이며 full-cycle 실제 구동을 대체하지 않는다. +- model: dev OpenAI-compatible profile을 띄운 경우 `iop-edge smoke openai --base-url http://127.0.0.1:18083` +- full-cycle: repo 내부 edge-node 진단, `iop-edge smoke openai`, OpenAI-compatible 입력 표면 수동 검증 + +## 필수 검증 + +- 변경한 edge 패키지 또는 `go test ./apps/edge/...`를 실행한다. +- registry, service, transport, console, HTTP/A2A 입력 표면을 바꾼 경우 edge-node 메시지 2회 왕복과 command 응답을 확인한다. +- OpenAI-compatible 경계를 바꾼 경우 dev `18083` 기준 `iop-edge smoke openai` 또는 동등한 `/healthz`, `/v1/models`, `/v1/responses` 확인으로 edge service와 node adapter 경로 수렴을 확인한다. +- bootstrap/artifact 경계를 바꾼 경우 dev artifact/base URL 후보 `18082`가 local/test `18080` field baseline을 덮어쓰지 않는지 확인한다. + +## 보조 검증 + +- `./scripts/e2e-smoke.sh`는 edge-node 최소 생존 확인에 사용한다. +- `./scripts/e2e-openai-ollama.sh`는 OpenAI-compatible Ollama 입력 표면 보조 확인에 사용한다. + +## 판정 기준 + +- node 등록, `/nodes`, console 메시지 전송, 기대 payload를 포함한 `[node-*-message]` 출력, 같은 run의 complete event가 확인된다. +- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다. +- edge complete는 같은 run의 마지막 `[node-*-message]` 이후에만 정상이다. +- OpenAI-compatible smoke에서 `/healthz`, `/v1/models`, `/v1/responses`가 기대 상태로 응답한다. +- bootstrap 사용자 명령은 완성된 URL과 positional token 하나만 포함한다. + +## 기준 출력 예시 + +```text +edge> /nodes +[edge] sent run_id=... +[node-*-message] IOP_EXPECTED_REPLY +[node-*-event] complete +``` + +## 차단 기준 + +- dev host 또는 Edge-Node TCP port 접근이 불가능하다. +- 외부 CLI profile 검증에 필요한 CLI 설치, 계정, provider 상태가 없다. +- dev artifact/model/metrics 포트가 기존 field baseline과 충돌한다. + +## 보고 항목 + +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다. +- field baseline 포트(`18080`, `18081`, `19090`, `19092`)를 dev 전용 포트로 재사용하지 않는다. diff --git a/agent-test/dev/node-smoke.md b/agent-test/dev/node-smoke.md new file mode 100644 index 0000000..b44f33a --- /dev/null +++ b/agent-test/dev/node-smoke.md @@ -0,0 +1,100 @@ +--- +test_env: dev +test_profile: node-smoke +domain: node +verification_type: smoke +last_rule_updated_at: 2026-06-12 +--- + +# node-smoke dev 테스트 + +## 읽기 조건 + +- `apps/node/**` 변경 또는 node 실행, adapter, transport, router, store dev 검증 판단이 필요한 경우 + +## 적용 범위 + +- `apps/node/cmd/node/**` +- `apps/node/internal/bootstrap/**` +- `apps/node/internal/node/**` +- `apps/node/internal/runtime/**` +- `apps/node/internal/router/**` +- `apps/node/internal/transport/**` +- `apps/node/internal/adapters/**` +- `apps/node/internal/store/**` + +## 분류 + +- domain: node +- verification_type: smoke +- scope: node 실행 파이프라인과 edge 연결 baseline + +## 환경 + +- host: local checkout. dev host, external CLI profile, shared Edge runtime evidence가 필요하면 원격 runner를 사용한다. +- port: dev Edge-Node TCP transport `19003` +- runtime: Go `1.24` +- package manager: Go modules / Makefile +- docker: unit/smoke quick check는 Docker를 요구하지 않는다. compose dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다. +- external service: dev Edge runtime 주소 후보 `toki-labs.com:19003` +- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1` +- credential: token/secret 원문은 문서에 기록하지 않는다. + +## 명령 + +- setup: +- lint: +- unit: `go test ./apps/node/...` +- smoke: `./scripts/e2e-smoke.sh`는 기본 포트 임시 설정을 쓰는 보조 smoke이므로 dev 포트 override 필요 여부를 먼저 확인한다. +- e2e: `make test-e2e` +- model: +- full-cycle: repo 내부 edge-node 진단과 사용자 실행 cycle 수동 검증 + +## 필수 검증 + +- 변경한 node 패키지 또는 `go test ./apps/node/...`를 실행한다. +- 실행 요청, stream, cancel, status, session, adapter registry 경로를 바꾼 경우 repo 내부 edge-node 진단과 full-cycle 실제 구동 기준을 함께 적용한다. +- CLI profile 변경 시 `/capabilities`, `/transport`, `/sessions`, persistent profile이면 `/terminate-session`을 확인한다. +- dev Edge runtime으로 연결하는 경우 Node가 `19003`을 사용하고 local/test `19090` field baseline으로 붙지 않는지 확인한다. + +## 보조 검증 + +- `./scripts/e2e-smoke.sh`는 mock adapter 기반 보조 smoke로 사용한다. +- `make test-e2e`는 보조 smoke이며 full-cycle 실제 구동을 대체하지 않는다. + +## 판정 기준 + +- node 등록 후 edge console에서 node가 조회된다. +- 같은 session에서 메시지 2회가 start, 기대 payload를 포함한 `[node-*-message]`, 같은 run의 complete 순서로 edge 화면에 도착한다. +- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다. +- edge complete는 같은 run의 마지막 `[node-*-message]` 이후에만 정상이다. +- command 결과가 `[node-*-]` 또는 명확한 성공/unsupported/error 출력으로 edge 화면에 표시된다. + +## 기준 출력 예시 + +```text +edge> /nodes +edge> Convert token iop_manual_one and reply only with converted token +[node-*-event] start +[node-*-message] IOP_MANUAL_ONE_OK +[node-*-event] complete +``` + +## 차단 기준 + +- dev host 또는 Edge-Node TCP port 접근이 불가능하다. +- 외부 CLI profile 검증에 필요한 CLI 설치, 계정, provider 상태가 없다. + +## 보고 항목 + +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- 사용자 실행 파이프라인 변경을 unit test만으로 완료 처리하지 않는다. +- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다. +- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다. diff --git a/agent-test/dev/platform-common-smoke.md b/agent-test/dev/platform-common-smoke.md new file mode 100644 index 0000000..a2fc0e9 --- /dev/null +++ b/agent-test/dev/platform-common-smoke.md @@ -0,0 +1,92 @@ +--- +test_env: dev +test_profile: platform-common-smoke +domain: platform-common +verification_type: smoke +last_rule_updated_at: 2026-06-12 +--- + +# platform-common-smoke dev 테스트 + +## 읽기 조건 + +- `packages/go/**`, `proto/**`, `configs/**` 변경 또는 공통 설정, protobuf 계약, host setup dev 검증 판단이 필요한 경우 + +## 적용 범위 + +- `packages/go/**` +- `proto/iop/**` +- `proto/gen/iop/**` +- `configs/**` +- dev env/compose/config 계약 + +## 분류 + +- domain: platform-common +- verification_type: smoke +- scope: 공통 패키지, 설정, protobuf 계약 baseline + +## 환경 + +- host: local checkout. dev field/runtime evidence가 필요한 경우에만 원격 runner를 사용한다. +- port: dev Edge-Node TCP transport `19003`, dev Edge OpenAI-compatible HTTP 후보 `18083`, dev Portal/Control Plane wire test endpoint `19001`, dev artifact/bootstrap 후보 `18082`. +- runtime: Go `1.24` +- package manager: Go modules / Makefile +- docker: unit/codegen quick check는 Docker를 요구하지 않는다. compose dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다. +- external service: dev artifact/base URL 후보 `http://toki-labs.com:18082` +- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1` +- credential: token/secret 원문은 문서에 기록하지 않는다. + +## 명령 + +- setup: +- lint: +- unit: `go test ./packages/go/... ./proto/gen/...` +- smoke: `go test ./...` +- e2e: `make test-e2e` +- model: +- full-cycle: 설정/proto 변경이 사용자 실행 파이프라인에 닿으면 edge-node 실제 구동 검증 + +## 필수 검증 + +- 공통 패키지 변경 시 변경 패키지 테스트 또는 `go test ./packages/go/... ./proto/gen/...`를 실행한다. +- protobuf 원본 변경 시 `make proto`로 Go 생성물을 갱신하고 생성물 diff를 확인한다. +- config 계약 변경 시 `packages/go/config` struct/default와 `configs/*.yaml` 예시가 일치하는지 확인한다. +- dev env/compose 계약 변경 시 `.env.dev.example`, `docker-compose.yml`, `agent-test/dev/rules.md`의 포트가 서로 일치하는지 확인한다. + +## 보조 검증 + +- `go test ./...`는 저장소 전체 회귀 확인으로 사용한다. +- 실행 경로에 닿는 config/proto 변경은 `make test-e2e`를 보조 확인으로 사용할 수 있다. + +## 판정 기준 + +- 공통 패키지는 앱 내부 패키지를 import하지 않는다. +- proto 생성물은 원본 proto와 `make proto` 결과로만 갱신된다. +- 설정 예시는 loader/default와 어긋나지 않는다. +- dev 포트는 local/test 포트를 덮어쓰지 않고 dev profile에서만 사용된다. + +## 기준 출력 예시 + +```text +go test ./packages/go/... ./proto/gen/... +``` + +## 차단 기준 + +- `protoc` 또는 `protoc-gen-go`가 없어서 proto 생성 검증을 실행할 수 없다. +- config 변경이 실제 환경값이나 credential 없이는 판정 불가능하다. + +## 보고 항목 + +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다. +- 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다. +- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다. diff --git a/agent-test/dev/rules.md b/agent-test/dev/rules.md new file mode 100644 index 0000000..6729c99 --- /dev/null +++ b/agent-test/dev/rules.md @@ -0,0 +1,67 @@ +--- +test_env: dev +last_rule_updated_at: 2026-06-12 +--- + +# dev 테스트 규칙 + +**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.** +**dev 테스트 환경은 local 테스트 조건을 그대로 따르되, 같은 원격 host에서 local/test stack과 공존하도록 host publish 포트와 compose project/network를 분리한다.** + +## 공통 규칙 + +- dev 테스트/검증은 이 파일을 기준으로 판단한다. +- 작업 완료 검증은 변경 범위 기준으로 선택한다. +- 필수 검증을 실행하지 못하면 차단 사유로 보고한다. +- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다. +- 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다. +- token/secret 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다. +- 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose `networks`, IPAM subnet, static IPv4, `extra_hosts`, host publish 문서 어디에도 `192.168.0.0/24` (`192.168.0.X`) 대역을 사용하지 않는다. +- 새 Docker 테스트 subnet이 필요하면 기존 프로젝트 포트/네트워크 표준을 먼저 따르고, 불가피한 경우 host LAN/VPN과 충돌하지 않는 `192.168.0.0/24` 밖의 private subnet만 사용한다. + +## 기본 환경 + +- host: dev runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다. +- repo root: 명령은 원격 checkout `/Users/toki/agent-work/iop-dev` 기준으로 실행한다. +- sync 기준: 원격 runner를 사용하는 경우 local uncommitted 변경은 원격 repo에 자동 반영되지 않는다. 동기화되지 않았으면 현재 변경분 검증으로 보지 않는다. +- env file: dev stack은 `docker compose --env-file .env.dev.example ...`로 명시한다. +- compose identity: `COMPOSE_PROJECT_NAME=iop-dev-agent`, `IOP_COMPOSE_NETWORK=iop-dev-agent-net`. +- port: web/dev preview `13001`, Control Plane HTTP `18001`, Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, Postgres host publish `15401`, Redis host publish `16301`. +- optional dev field ports: artifact/bootstrap HTTP `18082`, Edge OpenAI-compatible HTTP `18083`, Edge metrics `19101`. 이 값은 compose 기본 stack에 publish되지 않으며 field/bootstrap 또는 Edge direct dev profile이 필요할 때만 사용한다. +- runtime: Go quick check는 local toolchain을 우선한다. Flutter client 포함 검증과 Docker/code-server/full-cycle runtime은 원격 runner를 사용한다. +- package manager: Go modules / Makefile / Flutter pub +- docker: 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않는다. Docker compose 검증은 원격 runner 또는 code-server 환경에서 수행한다. +- external service: dev compose Control Plane HTTP `http://toki-labs.com:18001`, dev Client wire `ws://toki-labs.com:19001/client`. +- model endpoint: dev Edge OpenAI-compatible profile을 별도로 띄우는 경우 `http://toki-labs.com:18083/v1`. +- credential: token/secret 원문은 문서에 기록하지 않는다. + +## 포트 매핑 + +| 용도 | local/test | dev | +|---|---:|---:| +| Web preview | `13000` | `13001` | +| Control Plane HTTP | `18000` | `18001` | +| CP Client WS | `19080` | `19001` | +| CP-Edge wire | `19081` | `19002` | +| Edge-Node TCP | `19090` | `19003` | +| Edge artifact/bootstrap | `18080` | `18082` | +| Edge OpenAI-compatible | `18081` | `18083` | +| Edge metrics | `19092` | `19101` | +| PostgreSQL host publish | `15400` | `15401` | +| Redis host publish | `16300` | `16301` | + +## 라우팅 + +- node / smoke / node 실행 파이프라인 baseline: `agent-test/dev/node-smoke.md` +- edge / smoke / edge 실행 그룹과 입력 표면 baseline: `agent-test/dev/edge-smoke.md` +- control-plane / smoke / control-plane health와 wire baseline: `agent-test/dev/control-plane-smoke.md` +- client / smoke / Flutter client와 IOP console package baseline: `agent-test/dev/client-smoke.md` +- platform-common / smoke / 공통 설정과 protobuf 계약 baseline: `agent-test/dev/platform-common-smoke.md` +- testing / smoke / 테스트 도구와 full-cycle 검증 baseline: `agent-test/dev/testing-smoke.md` + +## 라우팅 규칙 + +- 여러 항목이 맞으면 모두 읽는다. +- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `-smoke` 문서를 기본 baseline으로 둔다. +- 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다. +- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다. diff --git a/agent-test/dev/testing-smoke.md b/agent-test/dev/testing-smoke.md new file mode 100644 index 0000000..e218eb0 --- /dev/null +++ b/agent-test/dev/testing-smoke.md @@ -0,0 +1,105 @@ +--- +test_env: dev +test_profile: testing-smoke +domain: testing +verification_type: smoke +last_rule_updated_at: 2026-06-12 +--- + +# testing-smoke dev 테스트 + +## 읽기 조건 + +- `Makefile`, `scripts/dev/**`, `scripts/e2e-*.sh`, bootstrap pack, 테스트/검증 절차, dev compose/profile 변경 판단이 필요한 경우 + +## 적용 범위 + +- `Makefile` +- `scripts/dev/edge.sh` +- `scripts/dev/node.sh` +- `scripts/e2e-smoke.sh` +- `scripts/e2e-openai-ollama.sh` +- `iop-edge bootstrap pack` +- `docker-compose.yml` +- `.env.dev.example` +- `agent-test/dev/**` + +## 분류 + +- domain: testing +- verification_type: smoke +- scope: 테스트 도구, 보조 smoke, full-cycle 실제 구동 기준 + +## 환경 + +- host: local checkout. Flutter client 포함 검증, Docker compose, field/bootstrap, artifact server, external CLI profile evidence가 필요하면 원격 runner를 사용한다. +- port: web/dev preview `13001`, artifact/bootstrap HTTP 후보 `18082`, Edge OpenAI-compatible HTTP 후보 `18083`, Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, Edge metrics 후보 `19101`. +- runtime: Go `1.24` +- package manager: Go modules / Makefile +- docker: quick check는 Docker를 요구하지 않는다. 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않으며, Docker compose 검증은 원격 runner 또는 code-server 환경에서 수행한다. +- external service: dev Control Plane HTTP `http://toki-labs.com:18001`, dev Client wire `ws://toki-labs.com:19001/client`, dev Edge runtime 후보 `toki-labs.com:19003` +- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1` +- credential: token/secret 원문은 문서에 기록하지 않는다. + +## 명령 + +- setup: +- lint: +- unit: `make test` +- smoke: `./scripts/e2e-smoke.sh` +- compose-smoke: `IOP_EDGE_NODE_TOKEN= docker compose --env-file .env.dev.example up -d postgres redis control-plane edge web` +- compose-health: `curl -fsS http://127.0.0.1:18001/healthz` +- e2e: `make test-e2e` +- model: `./scripts/e2e-openai-ollama.sh` +- full-cycle: `make pack-node-target`, repo 내부 edge-node 진단, field bootstrap UX, 실제 외부 CLI profile 검증 + +## 필수 검증 + +- 테스트 도구 자체를 바꾼 경우 해당 도구를 직접 실행해 성공/실패 판정을 확인한다. +- 사용자 실행 파이프라인에 닿는 변경은 일반 Go 테스트와 변경 범위에 맞는 full-cycle 실제 구동을 함께 검증한다. +- dev compose/profile 변경 시 `docker compose --env-file .env.dev.example config`로 렌더링된 host publish 포트와 network name을 확인한다. +- `iop-edge bootstrap pack`, `make pack-edge`, 내장 artifact server 변경 시 현재 host target build와 artifact/checksum/bootstrap script를 확인한다. +- field/bootstrap/deploy 작업은 one-line bootstrap UX 기준을 적용한다. +- 사용자에게 전달하는 Node bootstrap 명령은 완성된 URL과 token positional value 하나만 포함한다. + +## 보조 검증 + +- `make test-e2e`, `./scripts/e2e-smoke.sh`, `./scripts/e2e-openai-ollama.sh`는 보조 smoke다. +- 보조 smoke는 full-cycle 실제 구동이나 field bootstrap 검증을 대체하지 않는다. + +## 판정 기준 + +- dev compose는 `COMPOSE_PROJECT_NAME=iop-dev-agent`와 `IOP_COMPOSE_NETWORK=iop-dev-agent-net`을 사용한다. +- dev compose가 local/test 포트 `13000`, `18000`, `19080`, `19081`, `15400`, `16300`을 점유하지 않는다. +- edge console에서 메시지 2회가 각각 기대 payload를 포함한 `[node-*-message]`로 표시되고, command 결과가 edge 화면에 도착한다. +- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다. +- Node bootstrap UX는 `curl -fsSL <완성된-bootstrap-url> | bash -s ` 형태를 유지한다. + +## 기준 출력 예시 + +```text +docker compose --env-file .env.dev.example config +curl -fsS http://127.0.0.1:18001/healthz +``` + +## 차단 기준 + +- dev host 접근, 지정 port, 외부 CLI 설치/계정/provider 상태가 없어 필수 검증을 수행할 수 없다. +- 사용자가 명시하지 않았는데 code-server 컨테이너 재시작이 필요한 상황이다. +- dev 포트가 이미 사용 중이라 local/test stack과 공존할 수 없다. + +## 보고 항목 + +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- 보조 E2E smoke 통과만으로 완료 처리하지 않는다. +- 사용자 기본 경로에서 `IOP_ARTIFACT_BASE_URL=...`, `IOP_EDGE_ADDR=...`, `IOP_NODE_TOKEN=...` 같은 named environment parameter를 요구하지 않는다. +- 사용자가 명시하지 않으면 code-server 컨테이너를 재시작하지 않는다. +- 환경값을 사람용 docs나 roadmap에 복사하지 않는다. +- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다. diff --git a/docker-compose.yml b/docker-compose.yml index 8159c07..3fdd41e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -95,7 +95,7 @@ volumes: networks: default: - name: iop-dev-net + name: ${IOP_COMPOSE_NETWORK:-iop-dev-net} ipam: config: - subnet: 10.89.0.0/24