variet_llm/.planning/phases/03-cli-build-provider/03-PLAN.md

---
phase: 03
name: CLI Build & Provider Connection
wave: 1
depends_on: []
files_modified:
  - openclaude/.env
  - scripts/start_openclaude.bat
  - scripts/start_openclaude.ps1
autonomous: true
requirements: [BUILD-01, CONN-01, CONN-02]
---

# Phase 03: CLI Build & Provider Connection — PLAN

<objective>
OpenClaude CLI를 Machine B에서 빌드하고, Variet Engine(Machine A:8000)에 OpenAI-compatible 프로바이더로 연결하여, 기본적인 프롬프트-응답 루프가 동작하는 것을 확인한다.
</objective>

<tasks>

<task id="1" title="Install dependencies and build OpenClaude">

<read_first>
- openclaude/package.json
- openclaude/README.md (Source Build section)
</read_first>

<action>
1. openclaude/ 디렉토리에서 bun이 설치되어 있는지 확인:
   ```bash
   bun --version
   ```
   bun이 없으면 npm으로 설치:
   ```bash
   npm install -g bun
   ```

2. 의존성 설치:
   ```bash
   cd openclaude
   bun install
   ```

3. CLI 빌드:
   ```bash
   bun run build
   ```

4. 빌드 결과물 확인:
   ```bash
   node dist/cli.mjs --version
   ```
   버전(0.1.8)이 출력되어야 한다.

5. smoke 테스트:
   ```bash
   bun run smoke
   ```
</action>

<acceptance_criteria>
- openclaude/node_modules/ 디렉토리가 존재한다
- openclaude/dist/cli.mjs 파일이 존재한다
- `node openclaude/dist/cli.mjs --version` 실행 시 버전 번호가 출력된다 (exit code 0)
- `bun run smoke` exit code 0
</acceptance_criteria>

</task>

<task id="2" title="Configure Variet Engine provider connection">

<read_first>
- openclaude/.env.example (Option 5: Ollama/LM Studio pattern — same as llama-server)
- config/engine_models.json (현재 모델 목록)
- openclaude/README.md (Fastest OpenAI setup section)
</read_first>

<action>
1. Machine A의 IP 주소 확인 (LAN). 예시: 192.168.x.x

2. openclaude/.env 파일 생성 (Option 2: OpenAI 패턴 사용):
   ```
   CLAUDE_CODE_USE_OPENAI=1
   OPENAI_BASE_URL=http://<MACHINE_A_IP>:8000/v1
   OPENAI_API_KEY=variet-local
   OPENAI_MODEL=gemma-4-26b
   ```
   
   주의: 
   - OPENAI_API_KEY는 llama-server가 키 검증을 안 하므로 아무 값이나 가능
   - OPENAI_MODEL은 llama-server가 자동으로 로드된 모델 이름을 사용

3. openclaude/.env가 .gitignore에 포함되어 있는지 확인:
   ```bash
   grep "\.env" openclaude/.gitignore
   ```
</action>

<acceptance_criteria>
- openclaude/.env 파일이 존재한다
- openclaude/.env에 `CLAUDE_CODE_USE_OPENAI=1`이 포함되어 있다
- openclaude/.env에 `OPENAI_BASE_URL=http://` 로 시작하는 URL이 포함되어 있다
- openclaude/.env에 `OPENAI_API_KEY=`가 포함되어 있다
- .env 파일이 .gitignore에 의해 추적되지 않는다
</acceptance_criteria>

</task>

<task id="3" title="Create launcher scripts for Machine B">

<read_first>
- start_variet_engine.bat (Machine A용 런처 패턴 참고)
- openclaude/.env
</read_first>

<action>
1. scripts/start_openclaude.bat 생성:
   ```bat
   @echo off
   title OpenClaude CLI (Variet Engine)
   echo ============================================
   echo   OpenClaude CLI - Variet Engine Connection
   echo ============================================
   echo.
   
   REM Set provider for Variet Engine
   set CLAUDE_CODE_USE_OPENAI=1
   set OPENAI_BASE_URL=http://<MACHINE_A_IP>:8000/v1
   set OPENAI_API_KEY=variet-local
   set OPENAI_MODEL=gemma-4-26b
   
   REM Launch OpenClaude
   cd /d "%~dp0..\openclaude"
   node dist/cli.mjs %*
   ```

2. scripts/start_openclaude.ps1 생성 (PowerShell 버전):
   ```powershell
   $env:CLAUDE_CODE_USE_OPENAI = "1"
   $env:OPENAI_BASE_URL = "http://<MACHINE_A_IP>:8000/v1"
   $env:OPENAI_API_KEY = "variet-local"
   $env:OPENAI_MODEL = "gemma-4-26b"
   
   Push-Location "$PSScriptRoot\..\openclaude"
   node dist/cli.mjs @args
   Pop-Location
   ```
</action>

<acceptance_criteria>
- scripts/start_openclaude.bat 파일이 존재한다
- scripts/start_openclaude.ps1 파일이 존재한다
- .bat 파일에 `OPENAI_BASE_URL` 설정이 포함되어 있다
- .ps1 파일에 `OPENAI_BASE_URL` 설정이 포함되어 있다
</acceptance_criteria>

</task>

<task id="4" title="Validate end-to-end connection">

<read_first>
- openclaude/.env
- engine/variet_engine.py (health endpoint)
</read_first>

<action>
1. Machine A에서 Variet Engine이 실행 중인지 확인:
   ```bash
   curl http://<MACHINE_A_IP>:8000/engine/health
   ```
   응답: `{"state": "ready", "role": "fast"}` (또는 현재 로드된 role)

2. Machine B에서 OpenClaude 실행:
   ```bash
   cd openclaude
   node dist/cli.mjs
   ```
   
3. 프롬프트가 표시되면 간단한 테스트:
   ```
   > What is 2+2? Answer in one word.
   ```
   LLM 응답이 스트리밍으로 표시되어야 한다.

4. 연결 실패 시 디버깅:
   - Variet Engine 상태 확인: `curl http://<MACHINE_A_IP>:8000/engine/status`
   - 방화벽 확인: Machine A에서 8000 포트 오픈 여부
   - OPENAI_BASE_URL 경로 확인 (/v1 포함)
</action>

<acceptance_criteria>
- `curl http://<MACHINE_A_IP>:8000/engine/health`가 `"state": "ready"` 응답을 반환한다
- OpenClaude CLI가 실행되고 프롬프트가 표시된다
- 프롬프트에 텍스트를 입력하면 LLM 응답이 스트리밍으로 출력된다
- 응답 완료 후 다음 프롬프트가 다시 표시된다 (루프 동작)
</acceptance_criteria>

</task>

</tasks>

<verification>
## Must-Haves (Goal-Backward)

Phase 03의 목표는 "OpenClaude CLI가 Variet Engine에 연결되어 기본 대화가 가능한 상태"이다.

1. **빌드 성공**: `openclaude/dist/cli.mjs`가 존재하고 실행 가능
2. **프로바이더 연결**: `.env`에 Variet Engine URL이 설정되고 연결 성공
3. **프로필 저장**: 런처 스크립트로 재현 가능한 설정 보관
4. **기본 대화**: 프롬프트 → 응답 → 다음 프롬프트 루프 동작

## Final Verification Commands

```bash
# 1. Build exists
test -f openclaude/dist/cli.mjs && echo "PASS: build exists"

# 2. Env configured
grep "OPENAI_BASE_URL" openclaude/.env && echo "PASS: provider configured"

# 3. Launcher scripts exist  
test -f scripts/start_openclaude.bat && echo "PASS: bat launcher"
test -f scripts/start_openclaude.ps1 && echo "PASS: ps1 launcher"

# 4. Engine reachable (requires Machine A running)
curl -s http://<MACHINE_A_IP>:8000/engine/health | grep "ready" && echo "PASS: engine reachable"
```
</verification>