HAL 0.3.1: 서버에 설치된 CLI 자동 탐색·연결 가능화 — HAL 서비스 PATH 밖(~/.local/bin 등)의 Claude Code·Codex CLI 를 찾아 버전·로그인 상태·기본 모델을 AI 연동 화면에 보이고(GET /ops/api/ai/cli, "이 CLI 로 연결 추가"), Codex exec --json 지원, 로그인 안 됨은 cli_not_logged_in → reauth_required + 서버 로그인 안내, 확인 실패 응답 424(원인 표시), 점검 결과·개발 지시 v0.3.1(Oz)·docs/HAL-AI.md·VERSION_HISTORY 0.3.1 — test/hal-ai.test.mjs RED → GREEN 12/12, 전체 26파일 183건 통과

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 01:11:32 +00:00
parent 0d3a0b80e9
commit 3775b7bee4
14 changed files with 252 additions and 52 deletions
@@ -1,5 +1,54 @@
 # VERSION_HISTORY

+## 0.3.1 (2026-10-29)
+
+- **작성자**: 개발 지시 — Oz(`Ariweb-Suitle_Dev-Order_v0.3.1.md`, 2026-10-29) · 구현 — Claude Fable 5.1(브랜치 `feature/hal-cli-discovery-v0.3.1`, 기준 main `0d3a0b8` = 0.3.0). 커밋·push·`main` 병합·릴리스 빌드·bear `hal21.ariweb.net` HAL 배포까지 수행(아래 "배포").
+- **이전 버전**: 0.3.0(2026-10-29, HAL AI 채팅룸). 0.3.1 은 **끝 버전 번호만 올리는 결함 수정**: 운영 서버에 이미 설치된 CLI 를 HAL 이 찾지 못하던 문제. HAL 에만 적용, 다른 모듈 변경 없음(배포하지 않음).
+
+### 요구(사용자 요구 — 약화 없이 반영)
+bear 서버(HAL 운영 서버)에 이미 CLI 가 설치되어 있는데 설치된 것을 확인하지 못하고 있다. 서버의 설치 상황을 점검해서 이미 설치된 것은 찾아서 연결 가능하게 수정하라.
+
+### 점검 결과(bear, 2026-10-29, HAL 실행 계정 master)
+- 설치됨: Claude Code CLI **2.1.312** `~/.local/bin/claude` → `~/.local/share/claude/versions/2.1.312`, OpenAI Codex CLI **0.162.1** `~/.local/bin/codex` → `~/.codex/packages/standalone/current/bin/codex`. 로그인 셸 PATH 에는 `~/.local/bin` 이 있지만 **HAL 서비스(systemd) PATH 는 `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/snap/bin`** 이라 0.3.0 의 `cliBin()`(지정 경로 또는 PATH 의 `claude`)이 찾지 못했다. 이것이 원인.
+- 로그인: codex `login status` = "Logged in using ChatGPT"(기본 모델 `gpt-6.1-sol`, `~/.codex/models_cache.json` 11개). claude `auth status` = `loggedIn:false`, headless 실행 결과 "Failed to authenticate: OAuth session expired and could not be refreshed" → **claude 는 서버에서 `claude login` 이 필요**(HAL 이 대신할 수 없다).
+- 유닛 샌드박스(`ProtectSystem=strict`, `ReadWritePaths=/srv/ariweb/hal`)와 같은 조건으로 `systemd-run` 실행: `claude --version`·`claude -p`(인증 오류 JSON 반환)·`codex exec --json`("OK", usage) 모두 실행됨 — 유닛 변경 불필요.
+
+### 수정한 기존 기능
+- `hal/ai/providers.mjs`: CLI **자동 탐색**(`findCliBin`·`discoverClis`·`cliSearchDirs`) — 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. 로그인 상태(`cliLoginStatus`: claude `auth status` JSON / codex `login status`), codex 기본 모델·모델 목록(`~/.codex/config.toml`·`models_cache.json`, 숨김 제외). **Codex 지원**(`chatCodex`: `exec --json -s read-only --skip-git-repo-check --ephemeral -C <임시 폴더> -m <모델>`, JSONL 해석). Claude 의 `is_error` 결과(인증 만료)는 모델 답으로 꾸미지 않고 `cli_not_logged_in` 으로. CLI 환경 변수는 HOME·PATH(탐색 위치 포함)·LANG 등 최소.
+- `hal/ai/connections.mjs`: `cli.tool`(claude|codex) 검증, 모델 비우면 CLI 기본 모델, "확인" 때 탐색된 실행 파일·버전·로그인 상태를 연결에 기록, `cli_not_logged_in` → 상태 `reauth_required`. 확인 실패 응답은 5xx 대신 **424** 로(5xx 는 화면에 "일시적 오류"로 가려져 원인이 안 보였다).
+- `hal/ai/routes.mjs`: `GET /ops/api/ai/cli`(탐색 결과·탐색 위치·지원 CLI). `hal/ai/engine.mjs`: CLI 로그인 만료도 연결 상태 `reauth_required`.
+- 화면(`hal/ui.mjs`·`ai-render.mjs`·`ai.js`): AI 연동 화면에 "서버에서 찾은 CLI" 카드(실행 파일·실제 경로·버전·로그인 배지와 안내·기본 모델·"이 CLI 로 연결 추가"(양식 미리 채움)·"다시 탐색"), 연결 추가 양식에 CLI 종류(claude/codex) 선택과 경로 생략 시 자동 탐색 안내, 연결 표에 CLI 종류·버전·경로·로그인 상태.
+- 문서: `docs/HAL-AI.md` §2·§6, 개발 지시 `Ariweb-Suitle_Dev-Order_v0.3.1.md`. 버전 표기 0.3.1(package.json·README·Suite 버전 검사 테스트).
+
+### 고객 화면
+- 변경 없음.
+
+### 운영자 화면
+- AI 연동(`/ops/ai`): "서버에서 찾은 CLI" 카드. bear 에서는 Claude Code 2.1.312(로그인 필요 — `claude login` 안내)와 Codex 0.162.1(로그인됨, 기본 모델 gpt-6.1-sol)이 보이고, "이 CLI 로 연결 추가"로 바로 연결할 수 있다. 연결 뒤 "확인"을 누르면 상태가 `active`(codex) 또는 `reauth_required`(claude, 로그인 전)로 표시된다.
+- 운영자 조치: claude 를 쓰려면 bear 에서 `master` 계정으로 `claude login` 을 실행한 뒤 AI 연동 화면에서 "확인". codex 는 바로 연결 가능.
+
+### 보안 결정
+- HAL 은 CLI 의 세션 파일·자격(`~/.claude.json`, `~/.claude/.credentials.json`, `~/.codex/auth.json`)을 읽지도 넘기지도 않는다. 점검 때도 키 이름·존재 여부만 확인했다. 로그인은 서버에서 사람이 한다.
+- CLI 실행은 지정 또는 탐색된 **절대 경로의 실행 파일**만, 인자는 고정 형식(프롬프트는 인자 하나). Codex 는 읽기 전용 샌드박스·임시 폴더·세션 비보존으로 돈다. HAL 환경 변수(Vault 키 등)는 CLI 에 넘기지 않는다.
+- 연결 설정의 `cli.tool` 은 claude|codex 만, `cli.bin` 은 절대 경로만 받는다(상대 경로·다른 실행 파일 이름 거부).
+
+### 테스트
+- RED(구현 전): `test/hal-ai.test.mjs` 새 테스트 "0.3.1 CLI 자동 탐색…" → `GET /ops/api/ai/cli` 404 로 실패(+ 버전 0.3.1 검사 2건 실패). 통과 9 · 실패 3.
+- GREEN: `test/hal-ai.test.mjs` **12/12**(가짜 `HOME/.local/bin` 의 claude(로그인 만료)·codex(로그인됨) 스크립트, `HAL_CLI_HOME`·`HAL_CLI_DIRS` 로 탐색 위치 고정 — 탐색 API 결과·탐색 위치, codex 연결(tool 만) → 확인 active·모델 목록 → 대화 "OK from codex"·usage·`exec --json -s read-only --skip-git-repo-check --ephemeral -m gpt-6.1-sol` 인자, claude 연결 → 확인 424 `cli_not_logged_in` → `reauth_required` + `claude login` 안내, 모르는 tool 400, 빈 HOME → `cli_unavailable` + 탐색 위치). 중간 결함 1건을 테스트가 잡았다: 확인 실패를 502 로 내면 `lib/http` 가 메시지를 "일시적 오류"로 가려 원인이 안 보임 → 424.
+- targeted: `test/hal-ui.test.mjs` 7/7 · `test/hal-reauth-banner.test.mjs` 5/5 · `test/hal.test.mjs` 16/16 · `test/webmaker-visual-editor.test.mjs` 5/5.
+- 전체 Suite `node test/run.mjs`: **26개 파일 실패 0, 183건 통과**. 러너의 `docs/verification/local-e2e-*` 임시 파일 미커밋. 변경 파일 secret-like 스캔 0건.
+
+### 배포(bear `hal21.ariweb.net`, HAL 만)
+- 절차와 read-back 은 배포 뒤 이 절에 후속 커밋으로 기록한다.
+
+### 알려진 제한
+- claude 로그인 만료는 HAL 이 풀 수 없다(서버에서 `claude login`). 로그인 뒤 "확인"을 눌러야 상태가 바뀐다(자동 재확인 없음).
+- 로컬 CLI 연결은 대화·분석 전용(HAL 도구 없음). 도구가 필요하면 API 키/OAuth 연결을 쓴다(Codex 의 ChatGPT 로그인은 API 키가 아니라 도구 호출 경로가 없다).
+- gemini 등 다른 CLI 는 탐색하지 않는다(요청 시 CLI_TOOLS 에 추가).
+
+### 미확정 정책값
+- CLI 실행 시간 상한(기본 10분, 연결 설정 `cli.timeoutMs`), codex 샌드박스 모드(read-only 고정).
+
 ## 0.3.0 (2026-10-29)

 - **작성자**: 개발 지시 — Oz(`Ariweb-Suitle_Dev-Order_v0.3.0.md`, 2026-10-29) · 구현 — Claude Fable 5.1(브랜치 `feature/hal-ai-chat-v0.3.0`, 기준 origin/main `6bfde82c5ef607704cb05628dc33d9b6ef68c50f` = 0.2.1). 지시에 따라 커밋·push·`main` 병합·릴리스 빌드·bear `hal21.ariweb.net` HAL 배포까지 수행한다(아래 "배포" 절에 read-back).