oto/agent-test/local/rules.md

test_env	last_rule_updated_at
local	2026-06-12

local 테스트 규칙

현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다. 기본 local 테스트 환경은 원격 runner다. 현재 workspace checkout에서의 git diff --check와 문서/문법 수준 확인은 편집 직후 preflight로만 사용하고, Dart/Flutter/Go/runtime evidence는 원격 runner 기준으로 판단한다.

공통 규칙

• local 테스트/검증은 이 파일을 기준으로 판단한다.
• 작업 완료 검증은 변경 범위 기준으로 선택한다.
• 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
• 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
• 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
• 테스트용 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: 기본 실행 host는 ssh toki@toki-labs.com 원격 runner이며, checkout 기준 위치는 /Users/toki/agent-work/oto다.
• port: OTO Core HTTP workspace host publish 18020, Flutter client/web preview 13020. 제품 local fallback 127.0.0.1:8080은 compatibility 경로로만 해석한다.
• runtime: Dart SDK, Flutter SDK, Go toolchain
• package manager: dart pub, flutter pub, Go modules
• docker: 기본 local smoke는 Docker를 사용하지 않는다.
• external service: 없음
• model endpoint:
• credential: OTO_RUNNER_RELEASE_BASE_URL, enrollment token, private release host 원문은 tracked 파일에 기록하지 않고 원격 환경 또는 사용자 제공 값에서만 주입한다.

Workspace 포트/환경 체크리스트

• OTO Core host publish 표준은 backend 18020이다. 원격 runner에서 Core를 띄울 때는 make core-run 또는 OTO_CORE_ADDR=0.0.0.0:18020 go run ./cmd/oto-core 기준으로 검증한다.
• Flutter client/web preview 표준은 frontend 13020이다. preview 포트와 OTO_SERVER_HTTP_URL 서버 연결 URL을 혼동하지 않는다.
• 원격 runner에서 외부 브라우저/클라이언트가 Core에 접근해야 하면 OTO_SERVER_HTTP_URL=http://toki-labs.com:18020로 명시한다. remote-local process만 접근하면 http://localhost:18020도 허용한다.
• OTO owned wire/agent transport port는 아직 확정하지 않는다. 현재 OTO_SERVER_WIRE_URL fallback은 compatibility 값으로 보고 workspace project-owned slot에 넣지 않는다.
• OTO_RUNNER_RELEASE_BASE_URL과 bootstrap command 검증은 source of truth와 validation 기준만 기록한다. secret, token, private release host 원문은 tracked 문서와 테스트 규칙에 남기지 않는다.
• 독립 OTO Control Plane 검증에서 iop Edge/wire 포트를 OTO workspace 포트 표준으로 간주하지 않는다.

라우팅

• agent / smoke / OTO agent CLI, OTO Server registration, bootstrap script: agent-test/local/agent-smoke.md
• cli / smoke / CLI entrypoint, resource importer, scripts, package assets: agent-test/local/cli-smoke.md
• command / smoke / command implementations and data models: agent-test/local/command-smoke.md
• core / smoke / Application, tag system, composer, core utilities: agent-test/local/core-smoke.md
• framework / smoke / pubspec, analyzer options, dependency and generated-code boundary: agent-test/local/framework-smoke.md
• pipeline / smoke / pipeline execution and pipeline data model: agent-test/local/pipeline-smoke.md
• sample / smoke / sample YAML and template-facing examples: agent-test/local/sample-smoke.md
• scheduler / smoke / scheduler CLI and runtime: agent-test/local/scheduler-smoke.md

패키지 및 Makefile 대상 (Monorepo Targets)

• apps/runner (Dart CLI runner):
  • Setup: make runner-get 또는 cd apps/runner && dart pub get
  • Lint: make runner-analyze 또는 cd apps/runner && dart analyze
  • Test: make runner-test (현재 필수 runner 회귀) 또는 cd apps/runner && dart test
  • Legacy iop evidence: make runner-test-legacy-iop (수동 실행 전용)
• apps/client (Flutter OTO client app):
  • Setup: make client-get 또는 cd apps/client && flutter pub get
  • Lint: make client-analyze 또는 cd apps/client && flutter analyze
  • Test: make client-test 또는 cd apps/client && flutter test
  • Web preview: make client-run-web OTO_SERVER_HTTP_URL=http://toki-labs.com:18020 또는 cd apps/client && flutter run -d chrome --web-port=13020 --dart-define=OTO_SERVER_HTTP_URL=http://toki-labs.com:18020
• services/core (Go OTO Server):
  • Test: make core-test 또는 cd services/core && go test ./...
  • Run: make core-run 또는 cd services/core && OTO_CORE_ADDR=0.0.0.0:18020 go run ./cmd/oto-core
• packages/flutter/oto_console (Flutter OTO console package):
  • Setup: cd packages/flutter/oto_console && flutter pub get
  • Lint: cd packages/flutter/oto_console && flutter analyze
  • Test: cd packages/flutter/oto_console && flutter test
• protobuf (proto contract):
  • Generate: make proto (또는 make proto-go, make proto-dart)

라우팅 규칙

• 여러 항목이 맞으면 모두 읽는다.
• 도메인 매핑이나 domain rule이 있으면 각 도메인의 <domain>-smoke 문서를 기본 baseline으로 둔다.
• 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다.
• 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.