AriWeb-Suite/Ariweb-Suitle_Dev-Order_v0.3.1.md

Ariweb Suite 개발 지시 — 작성자: Oz · v0.3.1

작성자: Oz 작성일: 2026-10-29 이전 버전: v0.3.0(HAL AI 채팅룸, Oz, 2026-10-29) · v0.2.1(HAL 고위험 재인증 안내 위치, Neo) · v0.2.0(Webmaker 직접 편집, Neo) · v0.1.4 · v0.1.1 이번 개정: HAL 0.3.0 의 로컬 CLI 연결이 bear(HAL 운영 서버)에 이미 설치된 CLI 를 찾지 못하는 결함 수정. 결함 수정이므로 끝 버전 번호만 올린다 — HAL 0.3.0 → 0.3.1. HAL 에만 적용하며 이전 지시의 모든 기준은 그대로다.

개정 이력

• v0.3.0 · Oz · 2026-10-29: HAL 운영자 콘솔 AI 채팅룸(통합 방 + 개별 방), 모델 연결(로그인·OAuth·API 키), 스킬·도구·MCP.
• v0.3.1 · Oz · 2026-10-29: 서버 설치 CLI 자동 탐색·연결 가능화(Claude Code·Codex), 로그인 상태 표시.

1. 사용자 요구(Oz 원문, 약화 금지)

bear 서버(HAL 운영 서버)에 이미 CLI 가 설치되어 있는데 설치된 것을 확인하지 못하고 있습니다. 서버의 설치 상황을 점검해서 이미 설치된 것은 찾아서 연결 가능하게 수정하세요.

2. 점검(구현 전 실제 확인)

• 설치 위치: ~/.local/bin/claude(Claude Code 2.1.312), ~/.local/bin/codex(Codex 0.162.1). HAL 실행 계정의 로그인 셸 PATH 에는 있으나 systemd 서비스 PATH 에는 ~/.local/bin 이 없다 → 0.3.0 의 "PATH 의 claude" 탐색이 실패한 원인.
• 로그인: codex 는 ChatGPT 로 로그인됨(기본 모델 gpt-6.1-sol). claude 는 OAuth 세션 만료(claude auth status loggedIn=false) — 서버에서 claude login 필요.
• 유닛 샌드박스(ProtectSystem=strict)와 같은 조건에서 두 CLI 모두 실행 가능 → 유닛·권한 변경 없이 코드 수정으로 해결.

3. 필수 동작(계약)

1. HAL 이 서버에 설치된 CLI(claude·codex)를 서비스 PATH 와 무관하게 자동 탐색한다: 환경 변수(CLAUDE_BIN·CODEX_BIN) → HAL_CLI_DIRS → HOME 의 알려진 설치 위치(~/.local/bin, ~/.npm-global/bin, ~/.claude/local, ~/.codex/packages/standalone/current/bin, ~/node_modules/.bin) → /usr/local/bin·/usr/bin → PATH. 심볼릭 링크도 인정.
2. GET /ops/api/ai/cli 와 AI 연동 화면 "서버에서 찾은 CLI" 카드가 실행 파일·실제 경로·버전·로그인 상태(claude auth status, codex login status)·기본 모델·모델 목록(codex ~/.codex/models_cache.json, 숨김 제외)과 탐색 위치를 보인다. "이 CLI 로 연결 추가"는 양식을 미리 채운다.
3. 연결은 cli.tool(claude|codex)만으로 만들 수 있고(경로 생략 → 탐색 결과), 모델을 비우면 CLI 기본 모델. "확인"은 탐색된 경로·버전·로그인 상태를 연결에 남기고, 로그인 안 됨이면 cli_not_logged_in(상태 reauth_required)과 "서버에서 claude login/codex login" 안내를 낸다. 실행 파일이 없으면 cli_unavailable 과 탐색 위치를 낸다. 확인 실패 응답은 메시지가 보이도록 5xx 가 아닌 424.
4. Codex 는 codex exec --json -s read-only --skip-git-repo-check --ephemeral -C <임시 폴더> -m <모델> <프롬프트> 로 실행하고 item.completed(agent_message) 를 답, turn.completed.usage 를 사용량으로 쓴다. Claude 는 기존 -p --output-format json. 인증 오류 결과는 모델 답으로 꾸미지 않는다.
5. HAL 은 CLI 의 세션 파일·자격을 읽지도 넘기지도 않는다. CLI 환경 변수는 HOME·PATH·LANG 등 최소. 절대 경로 실행 파일만, cli.tool 은 claude|codex 만.

4. TDD·검증

• test/hal-ai.test.mjs 에 자동 탐색 테스트를 먼저 추가해 RED 를 확인한다(가짜 HOME/.local/bin 의 claude(로그인 만료)·codex(로그인됨) 스크립트, HAL_CLI_HOME·HAL_CLI_DIRS 로 탐색 위치 고정): 탐색 API 결과, codex 연결(tool 만) → 확인 active → 대화 "OK from codex" 와 exec 인자, claude 연결 → 확인 424 cli_not_logged_in → reauth_required, 모르는 tool 거부, 빈 HOME 에서 cli_unavailable.
• GREEN 뒤 targeted(HAL UI·재인증·HAL) 와 전체 Suite 테스트. 배포 뒤 bear 에서 배포 코드의 탐색 결과(실제 claude·codex)를 read-back 한다.

5. 버전·배포

• HAL 0.3.1: package.json·README·VERSION_HISTORY 0.3.1 절·docs/HAL-AI.md. 커밋 → push → main 병합 → 깨끗한 main 에서 릴리스 빌드·verify → bear 에 HAL 만 배포(사전 백업·stage 검증·register-release --approve·bootstrap-release·current 전환·재시작) → /api/health·/ops/api/ai/cli read-back. 다른 모듈은 바뀌지 않았으므로 배포하지 않는다.

6. 완료 조건

점검 결과(설치 경로·버전·로그인 상태·원인), 변경 파일, RED/GREEN·전체 테스트, 커밋·병합 커밋, artifact sha256, 배포 read-back(탐색 결과 포함), 운영자가 해야 할 남은 조치(claude login)를 보고한다.