2nd/10_Wiki/Topics/G1nation_Build_Fix_Report.md

[Report] G1nation Extension Encoding & Engine Rebuilding

Date: 2026-04-24 Author: PD Kodari (AI) Status: COMPLETED & PACKAGED (v2.2.15)

1. 개요 (Overview)

ConnectAI에서 G1nation으로의 브랜딩 전환 이후 발생한 심각한 빌드 오류 및 런타임 불안정성을 해결하기 위한 긴급 수술을 집행함. 소스 코드 내 인코딩 오염과 코드 복제(Duplication)로 인해 npm run compile이 불가능한 상태였음.

2. 주요 결함 (Critical Issues)

• 인코딩 지뢰 (Encoding Corruption): extension.ts 내 한글 주석 및 UI 문자열이 UTF-8 형식을 벗어나 깨지면서 따옴표(') 인식을 방해함 -> Unterminated string literal 에러 발생.
• 좀비 코드 (Ghost Blocks): 함수 외부에 버려진 실행 코드와 닫는 중괄호(})들이 산재하여 문법 파괴.
• 엔진 중복 (Engine Duplication): _executeActions 함수가 두 군데 이상 중복 정의되어 로직 충돌 및 용량 비대화 초래.
• 문법 오용: execSync에 .catch()를 사용하는 등 동기/비동기 혼선 발견.

3. 수술 과정 (Surgical Process)

총 20단계에 걸친 **PowerShell 레이저 수술(Line-by-line Patch)**을 통해 표준 replace 도구의 인코딩 한계를 극복함.

• v1~v10: 설정 메뉴(_handleSettingsMenu) 및 브레인 메뉴(_handleBrainMenu)의 깨진 텍스트를 영문/표준 UTF-8로 전면 교체.
• v11~v18: 중복된 코드 블록들을 찾아내어 삭제하고, 흩어진 액션 핸들러들을 하나로 통합.
• v19: 메인 엔진(_executeActions)을 중복 없는 최신 구조로 리빌딩.
• v20: 함수 외부에 잔존하던 '유령 코드'와 깨진 문자열 최종 소거.

4. 최종 결과 (Final Result)

• 빌드 성공: esbuild 컴파일 정상 통과 (30ms 내외).
• 패키징 완료: g1nation-2.2.15.vsix 생성 완료.
• 안정성 확보: UI 텍스트 영문화 및 표준화를 통해 향후 인코딩 문제 재발 가능성 차단.

5. 향후 과제 (Next Steps)

• 모듈화: 2,500라인이 넘는 extension.ts를 ActionHandlers.ts, UIProvider.ts 등으로 분리하여 유지보수성 향상 필요.
• i18n 도입: 한글 UI 재도입 시 직접 하드코딩 대신 별도의 JSON 언어팩 사용 권장.

---

PD 코다리의 한마디: "조직이 시스템이다. 엔진이 깨끗해야 비행기가 뜬다!" 😎🐟