leerness 1.9.32 → 1.9.34

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 1.9.34 — 2026-05-16
+
+**방향키 + 스페이스 인터랙티브 multi-select + 256색 그라데이션 배너 + 멀티레벨 sub-agent 오케스트레이션 검증**.
+
+### Added
+
+- **`_selectOne()` / `_selectMany()` 헬퍼**: TTY raw mode + readline 이벤트 처리.
+  - 방향키 ↑↓ (또는 j/k vim binding) — 커서 이동
+  - Space — 토글 (multi-select)
+  - a / n — 전체 선택 / 전체 해제
+  - Enter — 확정
+  - q / ESC / Ctrl+C — 취소 (기본값 또는 빈 배열 반환)
+- **`resolveInstallOptions`에 적용**: 언어 선택 + 스킬 라이브러리 선택을 multi-select UI로 전환.
+- **`setupAgentsCmd`에 적용**: 4 CLI 일괄 활성화를 Space 토글로 선택 (이전엔 각각 yes/no 4번).
+- **ASCII 배너 256색 그라데이션**: 6 라인을 cyan(51) → 자주(165)로 6단계 그라데이션. ★ 강조 + magenta 색 강조 항목.
+- **`--no-interactive-select` 플래그 + `LEERNESS_NO_INTERACTIVE=1` env**: 구식 숫자 prompt 폴백.
+
+### 멀티레벨 sub-agent 오케스트레이션 검증 (실측)
+
+메인 에이전트 → sub-agent(Claude) → sub-sub-agent(외부 gemini CLI) 3단계 깊이 검증.
+
+| 항목 | 결과 |
+|---|---|
+| 단일 gemini 호출 | ✅ 15.6s, 영문 번역 정상 |
+| 병렬 ×2 | ✅ 24s, 출력 분리 정상 (quota retry 1회) |
+| 효율 (순차 3회 33s vs 병렬 3회 15s) | **2.2× 향상** (이론 3× 대비 60%) |
+| 검수 체인 (결과 → 평가) | ✅ "2" → "yes" 정상 |
+| 같은 파일 동시 쓰기 | ⚠ **last-writer-wins, 락 없음 → 데이터 손실 위험** |
+
+**결론**:
+- 3단계 오케스트레이션 안전하게 동작
+- 독립 작업(번역/평가/리뷰) 2×+ 효율 향상
+- 같은 리소스 동시 쓰기는 호출자가 파일 경로 격리 책임
+- gemini quota 동시 호출 시 retry → 병렬 확장성 ~3개로 제한
+
+### Policy
+- ❌ 비-TTY/CI/`--yes` 시 multi-select prompt 자동 스킵 (defaults 사용)
+- ❌ 같은 파일/리소스 동시 쓰기 sub-agent 분배 금지 (호출자 책임)
+- ✅ 인터랙티브 prompt는 256색 ANSI 미지원 환경에서도 동작 (`LEERNESS_NO_INTERACTIVE=1` 폴백)
+- ✅ q/ESC로 언제든 취소 가능 (기본값으로 fallback)
+
+### 실측 (이번 라운드)
+- 워크스페이스 28 프로젝트 일괄 1.9.16~1.9.31 → 1.9.33 → 1.9.34 마이그레이션
+- e2e: 156/156 PASS (1.9.33 153 + multi-select 폴백 + 배너 + --no-interactive-select 3개)
+
+## 1.9.33 — 2026-05-15
+
+**npx 캐시 함정 방지 — install 시 stale 버전 자동 경고 + 해결 안내**.
+
+### 배경
+사용자가 `npx leerness init`(@latest 없이)을 실행하면 npm/npx의 로컬 캐시에 있는 옛 버전이 무한히 재사용되는 함정이 있음. 1.9.32 publish 후에도 사용자 PC에서 1.9.21이 실행되는 사례 확인.
+
+### Added
+
+- **`_warnIfStale()` 헬퍼**: `install()` 진입 시 자동 호출.
+  - npm registry latest 비교 (`fetchNpmLatest` + 24h cache 재사용)
+  - 현재 실행 중인 VERSION이 registry latest보다 옛날이면 ⚠ 노랑색 경고 박스 출력
+  - 해결 명령 2가지 안내: `npx --yes clear-npx-cache && npx leerness@latest init .` 또는 `npm i -g leerness@latest`
+  - **init 자체는 계속 진행** (경고만 띄움 — 강제 차단 X)
+- **`--no-stale-check`** 플래그 + **`LEERNESS_NO_STALE_CHECK=1`** env 변수: 경고 스킵
+- **offline + 캐시 없음**: 비교 스킵 (네트워크 차단 환경 안전)
+- **offline + 캐시 fresh**: 캐시값으로 비교 (e2e 등 CI 환경에서도 동작)
+
+### Policy
+- ❌ 사용자 init 차단 안 함 (경고만, init은 계속 진행)
+- ✅ 24h 캐시로 매 init마다 npm view 호출 안 함 (cold-start만 12s timeout)
+- ✅ 네트워크 실패 시 silently skip — init 흐름 끊지 않음
+- ✅ `--no-stale-check`/env로 끄기 가능 (CI 친화)
+
+### 실측 (이번 라운드)
+- 사용자 PC: `npx leerness init` → 1.9.21 실행됨 (npm latest=1.9.32) — 1.9.33부터 install 시 즉시 경고
+- e2e: 153/153 PASS (1.9.32 151 + stale 경고/스킵 2)
+
 ## 1.9.32 — 2026-05-15
 
 **ASCII 배너 + `leerness setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도**.