# gRPC Proto 파일 경로 인식 오류 수정 (2026-04-21)

## 개요
Next.js(`dashboard`) 환경에서 `@kord/grpc-contracts` 패키지를 통해 gRPC 서비스를 이용할 때, `kord.proto` 파일을 찾지 못해 발생하는 `ENOENT` 에러를 해결했습니다.

## 문제 원인
1. **__dirname의 가변성**: Next.js 서버 사이드 번들링 과정에서 Webpack이 `__dirname`을 변조하거나 가상 경로(`/ROOT/...`)로 치환하여 실제 파일 시스템의 `.proto` 파일 위치를 가리키지 못함.
2. **정적 리소스 누락**: JS 파일 외의 `.proto` 파일이 빌드 결과물에 포함되지 않거나 모노레포의 심볼릭 링크 구조에서 경로 해석이 어긋남.

## 수정 내역

### 1. @kord/grpc-contracts 패키지 개선
- `src/index.js` 내의 `PROTO_PATH` 결정 로직에 폴백 시스템 도입.
- 기존 `__dirname` 기반 탐색이 실패할 경우, `process.cwd()`를 기준으로 한 프로젝트 루트 탐색 및 상대 경로 탐색(`../../packages/...`) 로직 추가.
- 환경 변수 `KORD_PROTO_PATH`를 통한 명시적 경로 지정 지원.

### 2. apps/dashboard 설정 업데이트
- `next.config.ts`에 `transpilePackages: ["@kord/grpc-contracts"]` 설정 추가.
- 이를 통해 Next.js가 해당 모노레포 패키지를 소스 레벨에서 직접 처리하여 경로 해석의 일관성을 확보함.

### 3. gRPC 연결 설정 및 호환성 개선
- `apps/dashboard/src/lib/grpc.ts`에서 기본 연결 주소를 `127.0.0.1`로 변경하여 IPv6 호환 이슈 해결.
- **Node.js v22 호환성 해결**: `apps/bot/src/shard.ts`에서 샤딩 프로세스 생성 시 발생하는 `ERR_METHOD_NOT_IMPLEMENTED` 에러를 해결하기 위해 `execArgv`를 `--import tsx`로 업데이트함.
- **구동 순서 최적화**: 봇 샤드 생성 완료 전에도 gRPC 서버가 즉시 응답할 수 있도록 시작 시퀀스를 조정함.

## 테스트 결과 (에이전트 직접 검증 완료)
- **독립 테스트 스크립트 실행 결과**:
  - 파일: `apps/dashboard/src/verify_grpc.ts`
  - 결과: `SUCCESS! Received response: { reply: 'Pong to Hello from verification script!' }`
- **입증 내용**:
  1. `@kord/grpc-contracts`를 통한 프로토 파일 로드 성공 (Path Resolution 해결).
  2. 봇과 대시보드 패키지 간의 gRPC 통신 성공 (Connection 해결).
  3. Node.js v22 환경에서의 봇 구동 안정성 확보.

## 의사 결정 (Decisions Made)
- Node.js v22의 ESM 로더 변경 사항에 대응하기 위해 `-r tsx` 대신 `--import tsx`를 사용하여 런타임 안정성을 확보함.
- 봇의 라이프사이클에 관계없이 gRPC 서버를 조기에 활성화하여 서비스 가용성을 높임.
