# Tech Stack

> AI 에이전트는 구현 전 이 문서를 확인하여 올바른 기술/버전을 사용합니다.

## 언어 & 런타임

| 항목 | 버전 | 경로/비고 |
|------|------|-----------| 
| Python | 3.12 (miniforge3) | `C:\ProgramData\miniforge3\envs\gravity_control\python.exe` |
| Node.js | 시스템 설치 | `node`, `npm` (PowerShell에서 `cmd /c npm` 권장) |
| TypeScript | 5.3+ | `extension/src/*.ts` → `tsc` → `extension/out/*.js` |

> [!IMPORTANT]
> Python은 **반드시** 위 miniforge3 경로를 사용. WindowsApps의 python stub은 동작하지 않음.

## 프레임워크 & 라이브러리

### Python (서버)

| 패키지 | 버전 | 용도 |
|--------|------|------|
| discord.py | 2.x | Discord 봇 (슬래시 명령, 버튼 UI, 이벤트) |
| aiohttp | 3.x | Gateway HTTP 서버 + WebSocket endpoint |
| watchdog | - | Brain 디렉토리 파일시스템 감시 |
| python-dotenv | - | .env 파일 로드 |
| PyJWT | - | ❌ 미사용 (자체 HMAC-SHA256 구현) |

### TypeScript (Extension)

| 패키지 | 용도 |
|--------|------|
| @types/vscode | VS Code Extension API 타입 |
| @types/node | Node.js 타입 |
| typescript | 컴파일러 |
| ws | WebSocket Hub 연결 (`.vscodeignore`에 `!node_modules/ws/**` 필수) |
| antigravity-sdk | AG RPC 호출 (로컬 임베드 `sdk/`) |

## 패키지 관리

| 측 | 도구 | 파일 |
|----|------|------|
| Python | pip | `requirements.txt` |
| Extension | npm | `extension/package.json` |

## 개발 도구 & 명령어

| 작업 | 명령어 |
|------|--------|
| **봇 실행** | `C:\ProgramData\miniforge3\envs\gravity_control\python.exe main.py` |
| **봇 실행 (gateway)** | `.env`에서 `BOT_MODE=gateway` 설정 후 위 명령 |
| **Extension 구문 검사** | `cd extension && npx tsc --noEmit` |
| **Extension 컴파일** | `cd extension && cmd /c npm run compile` |
| **Extension VSIX** | `cd extension && npx @vscode/vsce package --no-dependencies` |
| **Python 구문 검사** | `python -c "import ast; [ast.parse(open(f).read()) for f in ['bot.py','hub.py',...]]"` |
| **Hub WS 테스트** | `python tests/test_ws_hub.py` (서버 기동 상태에서) |

## 환경 변수 (.env)

### 필수

| 변수명 | 용도 | 기본값 |
|--------|------|--------|
| DISCORD_TOKEN | Discord 봇 토큰 | (필수) |
| DISCORD_GUILD_ID | Discord 서버 ID | (필수) |

### 선택

| 변수명 | 용도 | 기본값 |
|--------|------|--------|
| BRAIN_PATH | AG 브레인 경로 | `~/.gemini/antigravity/brain` |
| BOT_MODE | `local` / ~~`remote`~~ / `gateway` | `local` |

> [!WARNING]
> `BOT_MODE=remote` (Collector 모드)는 **deprecated**입니다. `gateway` 모드 + Extension WS를 사용하세요.
| DEBOUNCE_SECONDS | Watcher 디바운스 간격 | `5` |
| PROJECT_NAME | 프로젝트 이름 | `gravity_control` |

### Gateway 모드 전용

| 변수명 | 용도 | 기본값 |
|--------|------|--------|
| GATEWAY_PORT | Gateway HTTP/WS 포트 | `8585` |
| GATEWAY_API_KEY | REST API 인증 키 | (미설정 시 인증 미사용) |
| GRAVITY_HUB_SECRET | WS Hub JWT 서명 시크릿 (64char hex) | (미설정 시 인증 생략) |
| GRAVITY_REGISTRATION_CODE | Extension 등록 코드 (32char hex) | (미설정 시 인증 생략) |
| REMOTE_BRIDGE_URL | ~~Collector 원격 URL~~ | ⚠️ deprecated (remote 모드 전용) |

## Extension VS Code 설정

| 설정 키 | 용도 |
|---------|------|
| `gravityBridge.bridgePath` | Bridge 디렉토리 경로 |
| `gravityBridge.projectName` | 프로젝트 이름 (기본: git remote) |
| `gravityBridge.hubUrl` | Hub WS URL (예: `ws://localhost:8585/ws`) |
| `gravityBridge.registrationCode` | Hub 등록 코드 |

## 빌드 산출물

| 항목 | 경로 | 설명 |
|------|------|------|
| VSIX | `extension/gravity-bridge-{ver}.vsix` | VS Code 확장 패키지 |
| JS 출력 | `extension/out/*.js` | TypeScript 컴파일 결과물 |
| SDK 복사 | `extension/out/sdk/` | compile 시 자동 복사 |