proto-socket/agent-task/proto_restructure/PLAN.md

Proto 루트 디렉터리 독립화

이 파일을 읽는 구현 에이전트에게

각 항목의 체크리스트를 완료하면서 [ ]를 [x]로 표시하라. 중간 검증 명령은 해당 항목 구현 직후 실행하고, 출력을 CODE_REVIEW.md의 검증 결과 섹션에 붙여넣어라. 최종 검증도 마찬가지로 실행 후 출력을 기록하라. 계획과 다르게 구현한 부분은 이유와 함께 CODE_REVIEW.md의 "계획 대비 변경 사항"에 기록하라.

⚠️ 이 태스크는 모든 언어의 빌드 경로를 변경한다. 각 검증을 반드시 실행한 후 다음 단계로 넘어가라.

---

배경

현재 proto canonical source가 dart/lib/src/packets/message_common.proto에 위치한다. Dart는 5개 언어 구현체 중 하나이지만 동시에 스펙 원본의 저장소 역할을 하고 있어, 새 기여자에게 "proto = Dart 전용"으로 오해될 수 있다. proto/message_common.proto 루트 디렉터리로 이동하면:

• proto가 특정 언어 종속성 없이 독립 소스임이 명확해진다
• 새 언어 포팅 시 proto 위치가 자명해진다
• check_proto_sync.sh의 "canonical Dart proto"라는 명칭이 사라진다

언어별 proto 현황

언어	현재 위치	방식	변경 여부
Dart	dart/lib/src/packets/message_common.proto (canonical)	protoc --dart_out (generate_proto.sh)	제거 후 생성 경로 변경
Go	go/packets/message_common.proto (go_package 옵션 포함 복사본)	protoc --go_out (generate_proto.sh)	유지 (언어 옵션 필요), sync 비교 대상 변경
Kotlin	kotlin/src/main/proto/message_common.proto (java 옵션 포함 복사본)	Gradle protobuf 플러그인	유지 (언어 옵션 필요), sync 비교 대상 변경
TypeScript	typescript/src/packets/message_common_pb.ts (생성 결과물만, .proto 없음)	protoc-gen-es 수동 실행	영향 없음
Python	python/toki_socket/packets/message_common_pb2.py (생성 결과물만, .proto 없음)	protoc --python_out 수동 실행	영향 없음

의존 관계 및 구현 순서

[PROTO_MOVE-1] proto/ 생성 + generate_proto.sh 수정
→ [PROTO_MOVE-2] check_proto_sync.sh canonical 경로 변경
→ [PROTO_MOVE-3] PROTOCOL.md 업데이트
→ [PROTO_MOVE-4] dart/lib/src/packets/message_common.proto 제거

---

[PROTO_MOVE-1] proto/ 디렉터리 생성 및 generate_proto.sh 수정

문제

tools/generate_proto.sh가 Dart canonical에서 직접 생성한다.

# 현재
cd "$repo_root/dart"
protoc --dart_out=lib/src/packets lib/src/packets/message_common.proto

cd "$repo_root/go"
protoc --go_out=. --go_opt=paths=source_relative packets/message_common.proto

해결 방법

1. proto/message_common.proto 생성: dart/lib/src/packets/message_common.proto에서 언어 옵션 없이 그대로 복사 (현재 Dart canonical에는 언어 옵션이 없으므로 내용 동일).
2. generate_proto.sh의 Dart 생성 경로를 proto/에서 dart/lib/src/packets/로 출력하도록 변경.
3. Go 생성은 Go copy(go/packets/message_common.proto)에서 그대로 진행 (go_package 옵션 보존 필요).

Before (generate_proto.sh Dart 섹션):

(
  cd "$repo_root/dart"
  protoc --dart_out=lib/src/packets lib/src/packets/message_common.proto
)

After:

(
  protoc \
    --proto_path="$repo_root/proto" \
    --dart_out="$repo_root/dart/lib/src/packets" \
    message_common.proto
)

Go 섹션은 변경 없음 (Go는 자체 복사본에서 생성).

수정 파일 및 체크리스트

• proto/message_common.proto 생성 (dart canonical과 동일 내용)
• tools/generate_proto.sh — Dart 생성 섹션 경로 변경

테스트 없음 — generate_proto.sh 실행으로 검증

중간 검증

# protoc가 있는 환경에서 실행
tools/generate_proto.sh
# 오류 없이 완료

# 생성 결과가 기존과 동일한지 확인
cd dart && dart analyze
# No issues found

---

[PROTO_MOVE-2] check_proto_sync.sh canonical 경로 변경

문제

tools/check_proto_sync.sh의 canonical이 dart_proto 변수로 Dart 경로를 가리킨다.

dart_proto="$repo_root/dart/lib/src/packets/message_common.proto"

해결 방법

변수명과 경로를 proto/ 기준으로 변경한다.

Before:

dart_proto="$repo_root/dart/lib/src/packets/message_common.proto"
go_proto="$repo_root/go/packets/message_common.proto"
kotlin_proto="$repo_root/kotlin/src/main/proto/message_common.proto"

if [[ ! -f "$dart_proto" ]]; then
  echo "Missing canonical Dart proto: $dart_proto" >&2
  exit 1
fi
# ...
normalize_proto "$dart_proto" >"$tmp_dir/dart.proto"
normalize_proto "$go_proto" >"$tmp_dir/go.proto"
# ...
if ! cmp -s "$tmp_dir/dart.proto" "$tmp_dir/go.proto"; then
  echo "Proto schema mismatch: go/packets/message_common.proto must match the Dart canonical proto ..."
# ...

After:

canonical_proto="$repo_root/proto/message_common.proto"
go_proto="$repo_root/go/packets/message_common.proto"
kotlin_proto="$repo_root/kotlin/src/main/proto/message_common.proto"

if [[ ! -f "$canonical_proto" ]]; then
  echo "Missing canonical proto: $canonical_proto" >&2
  exit 1
fi
# ...
normalize_proto "$canonical_proto" >"$tmp_dir/canonical.proto"
normalize_proto "$go_proto" >"$tmp_dir/go.proto"
# ...
if ! cmp -s "$tmp_dir/canonical.proto" "$tmp_dir/go.proto"; then
  echo "Proto schema mismatch: go/packets/message_common.proto must match proto/message_common.proto ..."
# ...

수정 파일 및 체크리스트

• tools/check_proto_sync.sh — dart_proto → canonical_proto, 경로를 proto/message_common.proto로 변경
• tools/check_proto_sync.sh — 오류 메시지에서 "Dart canonical" 문구 제거
• tools/check_proto_sync.sh — normalize 비교 대상 변수명 일관성 수정

중간 검증

tools/check_proto_sync.sh
# Proto schemas are in sync.

---

[PROTO_MOVE-3] PROTOCOL.md Proto Source 섹션 업데이트

문제

PROTOCOL.md 하단 "Proto Source" 섹션이 Dart 경로를 canonical로 명시한다.

`dart/lib/src/packets/message_common.proto` is the canonical packet definition.
All language implementations must keep the same message schema and generate bindings from it.

해결 방법

`proto/message_common.proto` is the canonical packet definition.
All language implementations generate bindings from it.
Language-specific generation options (go_package, java_package, etc.) are kept in each
language's own proto copy under `go/packets/` and `kotlin/src/main/proto/`.

수정 파일 및 체크리스트

• PROTOCOL.md — "Proto Source" 섹션 경로 및 설명 업데이트

테스트 없음 — 문서 전용

중간 검증

grep "canonical" PROTOCOL.md
# proto/message_common.proto 언급
grep "dart/lib/src/packets/message_common.proto" PROTOCOL.md
# 출력 없음이 정상

---

[PROTO_MOVE-4] dart/lib/src/packets/message_common.proto 제거

문제

PROTO_MOVE-1~3 완료 후 dart/lib/src/packets/message_common.proto는 더 이상 canonical이 아니다. 그러나 여전히 파일로 남아 혼란을 줄 수 있다.

해결 방법

파일을 삭제한다. Dart 생성 결과물인 .pb.dart 파일들은 유지한다.

수정 파일 및 체크리스트

• dart/lib/src/packets/message_common.proto 삭제
• dart analyze — proto 파일 제거 후 여전히 No issues인지 확인

중간 검증

ls dart/lib/src/packets/
# message_common.pb.dart, message_common.pbenum.dart 등 생성 결과물만 존재
# message_common.proto 없음

cd dart && dart analyze
# No issues found
cd dart && dart test
# 전체 PASS

---

수정 파일 요약

파일	항목
proto/message_common.proto (신규)	PROTO_MOVE-1
tools/generate_proto.sh	PROTO_MOVE-1
tools/check_proto_sync.sh	PROTO_MOVE-2
PROTOCOL.md	PROTO_MOVE-3
dart/lib/src/packets/message_common.proto (삭제)	PROTO_MOVE-4

최종 검증

# proto sync 도구 검증
tools/check_proto_sync.sh
# Proto schemas are in sync.

# Dart
cd dart && dart analyze
# No issues found
cd dart && dart test
# 전체 PASS

# Go
cd go && go build ./...
# 빌드 성공

# Kotlin
cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle ./gradlew build
# BUILD SUCCESSFUL

# proto/ 파일 확인
ls proto/
# message_common.proto 존재
ls dart/lib/src/packets/
# *.pb.dart만 존재, message_common.proto 없음