@didim365/agent-cli-core 0.1.0

package/dist/docs/00_project/white_labeling/working_history/Phase_CLI/355/214/250/355/202/244/354/247/200/353/252/205/353/263/200/352/262/275_20260214.md

@@ -0,0 +1,238 @@
+# CLI 배포 패키지명 변경 작업 결과서
+
+> **작업일**: 2026-02-14 **작업자**: Claude Code (Opus 4.6) **브랜치**:
+> `DID/v0.1` **방법론**: TDD (Red → Green → Refactor) + Tidy First
+
+---
+
+## 1. 작업 목적
+
+CLI 배포 패키지명을 `@google/gemini-cli` → `@didim365/agent-cli`로 변경하여 독립
+브랜딩 적용.
+
+**범위**: `@google/gemini-cli` → `@didim365/agent-cli`, `@google/gemini-cli-core` →
+`@didim365/agent-cli-core`. `@google/gemini-cli-a2a-server`는 변경하지 않음.
+
+---
+
+## 2. 작업 결과 요약
+
+| Phase   | 내용                        | 변경 파일 수 | 결과    |
+| ------- | --------------------------- | ------------ | ------- |
+| Phase 1 | 소스 코드 + 테스트 변경     | 3            | ✅ PASS |
+| Phase 2 | 패키지 정의 + 빌드 스크립트 | 10           | ✅ PASS |
+| Phase 3 | 문서 일괄 변경              | 16           | ✅ PASS |
+| Phase 4 | 통합 검증                   | 0 (검증만)   | ✅ PASS |
+
+**총 변경 파일**: 29개 **총 변경 참조**: ~77개
+
+---
+
+## 3. Phase별 상세
+
+### Phase 1: 소스 코드 + 테스트 (TDD)
+
+**변경 파일**:
+
+1. `packages/cli/src/utils/installationInfo.ts` — 4곳 (pnpm/yarn/bun/npm update
+   명령)
+2. `packages/cli/src/utils/installationInfo.test.ts` — 10곳 (7 명령 + 3
+   파일경로)
+3. `packages/cli/src/utils/handleAutoUpdate.test.ts` — 11곳 (8 명령 + 3 name
+   필드)
+
+**TDD 사이클**:
+
+- RED: 기준선 36 테스트 PASS 확인
+- RED-VERIFY: 소스만 변경 → 4 failed / 13 passed (기대대로)
+- GREEN: 테스트 동기화 → 36 passed
+- REFACTOR: 하드코딩 유지 (기존 패턴 일관성)
+
+**이슈**: `replace_all`로 `@google/gemini-cli` → `@didim365/agent-cli` 치환 시
+import문의 `@didim365/agent-cli-core`도 함께 변경됨. 수동으로 import 복원.
+
+### Phase 2: 패키지 정의 + 빌드 스크립트
+
+**변경 파일**:
+
+1. `packages/cli/package.json` — name + publishConfig 추가
+2. `package.json` (root) — name 변경
+3. `scripts/build_sandbox.js` — pack 명령 + tgz 파일명 패턴 (4곳)
+4. `scripts/get-release-version.js` — 기본 패키지명 (2곳)
+5. `scripts/releasing/create-patch-pr.js` — 기본 패키지명 (2곳)
+6. `scripts/releasing/patch-comment.js` — npm install 문구 (1곳)
+7. `scripts/prepare-github-release.js` — 주석 + pkg.name (2곳)
+8. `scripts/tests/get-release-version.test.js` — 테스트 기대값 (4곳)
+9. `eslint.config.js` — no-restricted-imports 규칙 (2곳)
+10. `package-lock.json` — `npm install`로 자동 재생성
+
+### Phase 3: 문서 일괄 변경
+
+**Batch 1** (8 files, 31 replacements):
+
+- `README.md`, `docs/get-started/installation.md`, `docs/get-started/index.md`
+- `docs/get-started/gemini-3.md`, `docs/npm.md`, `docs/releases.md`
+- `docs/troubleshooting.md`, `docs/faq.md`
+
+**Batch 2** (8 files):
+
+- `docs/changelogs/latest.md`, `docs/changelogs/preview.md`,
+  `docs/changelogs/index.md`
+- `docs/release-confidence.md`, `docs/cli/uninstall.md`, `docs/cli/sandbox.md`
+- `docs/change_model/model_command_multi_provider_todolist.md`
+- `docs/change_model/model_command_multi_provider_plan.md`
+
+**보존한 파일**:
+
+- `CLAUDE.md`, `GEMINI.md` — `@didim365/agent-cli-core` 참조만 존재
+- `docs/00_project/ai_adapter/working_history/` — 역사적 기록
+- `docs/00_project/white_labeling/todolist/` — 메타 문서
+
+### Phase 4: 통합 검증
+
+| 항목                                  | 결과                                       |
+| ------------------------------------- | ------------------------------------------ |
+| `npm run build`                       | ✅ PASS                                    |
+| 변경 테스트 36개                      | ✅ 36 passed                               |
+| `npm run lint`                        | ✅ PASS                                    |
+| `npm run typecheck`                   | ✅ PASS                                    |
+| 잔존 `@google/gemini-cli` (소스/설정) | **0건**                                    |
+| CLI 전체 테스트                       | 339 passed / 7 failed (timeout, 변경 무관) |
+| Core 전체 테스트                      | 278 passed / 4 failed (timeout, 변경 무관) |
+
+---
+
+## 4. 주요 패턴 변경
+
+```diff
+# package.json
+- "name": "@google/gemini-cli"
++ "name": "@didim365/agent-cli"
++ "publishConfig": { "access": "public" }
+
+# 설치/업데이트 명령
+- npm install -g @google/gemini-cli@latest
++ npm install -g @didim365/agent-cli@latest
+
+# tgz 파일명
+- google-gemini-cli-{ver}.tgz
++ didim365-agent-cli-{ver}.tgz
+
+# ESLint self-import 방지
+- name: '@google/gemini-cli'
++ name: '@didim365/agent-cli'
+```
+
+---
+
+## 5. 교훈 (Lessons Learned)
+
+1. **`replace_all` 부분 문자열 주의**: `@google/gemini-cli` 치환 시
+   `@didim365/agent-cli-core` import도 변경됨. 접미사 포함
+   패턴(`@google/gemini-cli@`) 사용이 안전.
+2. **npm workspace명 변경 영향**: `package.json` name 변경 후 모든 `-w` 명령에서
+   새 이름 사용 필요.
+3. **publishConfig 필수**: scoped npm 패키지(`@didim365/...`)는
+   `"access": "public"` 설정 필요.
+4. **문서 변경 시 필터링**: `gemini-cli-core`, `gemini-cli-a2a` 참조를
+   보존하면서 CLI 전용 참조만 변경.
+
+---
+
+## 6. 리뷰 반영 — 추가 수정 (2026-02-14 2차)
+
+### 6.1 리뷰 피드백 3건
+
+| #   | 심각도 | 이슈                                                                                     | 조치                                       |
+| --- | ------ | ---------------------------------------------------------------------------------------- | ------------------------------------------ |
+| 1   | 높음   | Dockerfile:43 tgz 파일명 `google-gemini-cli-*.tgz` → 실제 `didim365-agent-cli-*.tgz` 불일치 | `Dockerfile` 수정: `didim365-agent-cli-*.tgz` |
+| 2   | 중간   | Dockerfile:50 CMD `["gemini"]` → bin `"didim"` 불일치                                    | `Dockerfile` 수정: `CMD ["didim"]`         |
+| 3   | 낮음   | todolist 테스트 명령 `node --test` → 실제 vitest                                         | todolist 수정: `npx vitest run ...`        |
+
+### 6.2 Core 패키지명 변경: `@google/gemini-cli-core` → `@didim365/agent-cli-core`
+
+**변경 범위**:
+
+- **패키지 정의** (6 files): `packages/core/package.json`,
+  `packages/cli/package.json`, `packages/a2a-server/package.json`,
+  `packages/test-utils/package.json`, `package.json` (root),
+  `packages/core/tsconfig.json`
+- **소스 코드** (434 TS/TSX files): `packages/cli/src/`, `packages/core/src/`,
+  `packages/a2a-server/src/`, `integration-tests/`, `evals/`
+- **스크립트** (6 JS files): `build_sandbox.js`, `prepare-github-release.js`,
+  `sandbox_command.js`, `telemetry.js`, `telemetry_utils.js`, `eslint.config.js`
+- **설정** (2 files): `CLAUDE.md`, `GEMINI.md`
+- **문서** (10 MD files): `installation.md`, `npm.md`, `releases.md`,
+  `local-development.md` 등
+- **Dockerfile** (1 file): core tgz 파일명
+
+**보존한 파일**:
+
+- `docs/00_project/ai_adapter/working_history/` — 역사적 기록 (8 files)
+
+**tgz 파일명 변경**:
+
+```diff
+- google-gemini-cli-core-{ver}.tgz
++ didim365-agent-cli-core-{ver}.tgz
+```
+
+### 6.3 검증 결과
+
+| 항목                                       | 결과                  |
+| ------------------------------------------ | --------------------- |
+| `npm install`                              | ✅ PASS (lock 재생성) |
+| `npm run build`                            | ✅ PASS               |
+| 변경 테스트 36개                           | ✅ 36 passed          |
+| `npm run lint`                             | ✅ PASS               |
+| `npm run typecheck`                        | ✅ PASS               |
+| 잔존 `@google/gemini-cli-core` (소스/설정) | **0건**               |
+| 잔존 `google-gemini-cli-core` (tgz 패턴)   | **0건**               |
+
+### 6.4 미변경 패키지 (추후 검토 필요)
+
+- `@google/gemini-cli-a2a-server` — 별도 제품으로 독립 검토 필요
+- `@google/gemini-cli-test-utils` — 비공개(private) 내부 패키지, 필요 시 별도
+  변경
+
+---
+
+## 7. 리뷰 반영 — 3차 수정 (2026-02-14)
+
+### 7.1 리뷰 피드백 2건
+
+| #   | 심각도 | 이슈                                                                                                                       | 조치                                                         |
+| --- | ------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| 1   | 중간   | `prepare-github-release.js:47` bin 이름이 `gemini`로 하드코딩 → GitHub release에서 `didim`이 아닌 `gemini` 명령으로 배포됨 | `pkg.bin = { didim: 'bundle/gemini.js' }`로 수정             |
+| 2   | 중간   | `generate-settings-schema.test.ts`, `generate-settings-doc.test.ts` 실패 → 스키마/문서 생성물 동기화 불일치                | `npm run schema:settings` + `npm run docs:settings`로 재생성 |
+
+### 7.2 검증 결과
+
+```
+npm run test:scripts → 6 passed / 1 failed (43 tests 중 42 passed)
+```
+
+- `generate-settings-schema.test.ts` — ✅ PASS
+- `generate-settings-doc.test.ts` — ✅ PASS
+- `patch-create-comment.test.js:82` — ❌ FAIL (한국어 locale 기존 이슈, 변경
+  무관)
+
+### 7.3 추가 변경 파일
+
+- `scripts/prepare-github-release.js` — bin 이름 `gemini` → `didim`
+- `schemas/settings.schema.json` — 스키마 재생성
+- `docs/cli/configuration.md` — 설정 문서 재생성
+- `docs/cli/settings.md` — 설정 문서 재생성
+
+---
+
+## 8. 미커밋 상태
+
+모든 변경사항은 미커밋 상태입니다. 사용자가 커밋을 요청하면 아래 커밋 전략 적용:
+
+```
+feat(cli): 설치/업데이트 명령 패키지명 @didim365/agent-cli로 변경
+feat(cli): 패키지명 @didim365/agent-cli + @didim365/agent-cli-core로 변경 + 빌드 스크립트 동기화
+docs: 설치/릴리스 문서 패키지명 @didim 스코프로 변경
+fix: Dockerfile tgz 파일명 + CMD 불일치 수정
+```

package/dist/docs/00_project/white_labeling//354/225/261/352/265/254/354/241/260.md

@@ -0,0 +1,310 @@
+# Gemini CLI 앱 구조
+
+> **작성일**: 2026-02-14 **기준 브랜치**: `DID/v0.1`
+
+---
+
+## 1. 패키지 구조
+
+```
+gemini-cli/
+├── packages/
+│   ├── cli/          # 터미널 UI (React/Ink)
+│   ├── core/         # 백엔드 로직 엔진
+│   ├── a2a-server/   # Agent-to-Agent HTTP 서버
+│   ├── test-utils/   # 테스트 헬퍼
+│   └── vscode-ide-companion/  # VS Code 확장
+├── integration-tests/ # E2E 통합 테스트
+├── evals/            # 모델 평가 테스트
+├── scripts/          # 빌드/릴리스/유틸 스크립트
+├── bundle/           # esbuild 번들 결과물 (배포용)
+├── Dockerfile        # 샌드박스 컨테이너 이미지
+└── docs/             # 문서
+```
+
+### 패키지 의존 관계
+
+```
+packages/cli ──────────────→ packages/core
+packages/a2a-server ───────→ packages/core
+packages/test-utils ───────→ packages/core
+integration-tests ─────────→ packages/core (직접 import)
+scripts/ ──────────────────→ packages/core (일부 스크립트)
+```
+
+---
+
+## 2. 각 패키지 역할
+
+### `packages/cli` — 터미널 UI 레이어
+
+| 항목   | 내용                                                      |
+| ------ | --------------------------------------------------------- |
+| 기술   | React + Ink (터미널용 React 프레임워크)                   |
+| 엔트리 | `src/gemini.tsx` → `AppContainer`                         |
+| 역할   | 사용자 입력 파싱, 터미널 렌더링, 설정 UI, 인증 다이얼로그 |
+| bin    | `didim` → `dist/index.js`                                 |
+
+**주요 디렉토리**:
+
+- `src/ui/` — React 컴포넌트, 화면 렌더링
+- `src/config/` — 설정 로딩, 확장 관리
+- `src/utils/` — 설치 정보, 자동 업데이트, **샌드박스 오케스트레이션**
+- `src/core/` — core 패키지 초기화 (`initializer.ts`)
+
+### `packages/core` — 백엔드 로직 엔진
+
+| 항목 | 내용                                              |
+| ---- | ------------------------------------------------- |
+| 기술 | TypeScript, LLM SDK들                             |
+| 역할 | LLM API 호출, 도구 실행, 프롬프트 구성, 정책 엔진 |
+| SDK  | `@google/genai`, `@anthropic-ai/sdk`, `openai`    |
+
+**주요 디렉토리**:
+
+- `src/providers/` — **멀티 LLM 어댑터** (Gemini, Claude, OpenAI)
+- `src/core/` — 콘텐츠 생성, 클라이언트, 토큰 관리
+- `src/tools/` — 내장 도구 (shell, file read/write, grep, glob, web-fetch, MCP)
+- `src/services/` — 셸 실행 서비스, 파일 탐색, 채팅 기록
+- `src/scheduler/` — 도구 스케줄링, 실행 오케스트레이션
+- `src/mcp/` — Model Context Protocol 클라이언트
+- `src/policy/` — 도구 승인/안전 정책
+- `src/agents/` — 에이전트 시스템
+- `src/telemetry/` — 관측성, 로깅
+
+### `packages/a2a-server` — Agent-to-Agent 서버
+
+| 항목 | 내용                                  |
+| ---- | ------------------------------------- |
+| 기술 | Express.js                            |
+| 역할 | 외부 에이전트가 CLI를 HTTP API로 호출 |
+| 포트 | `CODER_AGENT_PORT` (기본 41242)       |
+
+core와 동일한 백엔드를 사용하되, 터미널 UI 대신 HTTP 엔드포인트로 노출.
+
+### `packages/test-utils` — 테스트 유틸리티
+
+비공개(private) 패키지. PTY 관리, 테스트 픽스처 등 통합 테스트 헬퍼.
+
+---
+
+## 3. 실행 흐름
+
+### 사용자 요청 → 응답 사이클
+
+```
+1. 사용자 입력: "이 디렉토리의 파일 목록 보여줘"
+       ↓
+2. [cli] React UI가 입력 수신, core 전달
+       ↓
+3. [core] GeminiClient → LLM API 호출
+   (providers/ 레이어가 Gemini/Claude/OpenAI 중 선택)
+       ↓
+4. LLM 응답: tool_call { name: "list_directory", args: { path: "." } }
+       ↓
+5. [core] 정책 엔진 → 사용자 승인 확인 (confirmation-bus)
+       ↓
+6. [core] ToolExecutor → 해당 도구 실행
+   (shell, file, grep, glob, web-fetch, MCP 등)
+       ↓
+7. 도구 결과를 LLM에 다시 전달 → 다음 턴
+       ↓
+8. LLM 최종 텍스트 응답 생성
+       ↓
+9. [cli] 터미널에 마크다운 렌더링
+```
+
+### 도구 실행 상세
+
+```
+도구 요청 (LLM tool_call)
+  ↓
+ToolExecutor (core/scheduler/tool-executor.ts)
+  ├── Shell Tool → ShellExecutionService
+  │   ├── PTY 선택: node-pty > child_process
+  │   ├── 셸 환경 설정 (bash/zsh/fish)
+  │   └── 출력 스트리밍 (1초 간격)
+  │
+  ├── File Tools → read/write/edit 도구
+  │   └── 로컬 파일 시스템 직접 접근
+  │
+  ├── Grep/Glob → ripgrep, glob 패키지
+  │
+  ├── Web Fetch/Search → HTTP 요청
+  │
+  └── MCP Tools → 외부 MCP 서버 호출
+```
+
+---
+
+## 4. 샌드박스 시스템
+
+### 왜 필요한가?
+
+LLM이 도구를 통해 파일 삭제, 네트워크 접근 등 위험한 작업을 수행할 수 있음.
+샌드박스는 **CLI 프로세스 전체를 격리된 환경에서 실행**하여 호스트 시스템을
+보호.
+
+### 작동 원리
+
+```
+[샌드박스 없이]
+사용자 → CLI → LLM → 도구 → 호스트 OS에서 직접 실행 ⚠️
+
+[샌드박스 있을 때]
+사용자 → CLI 시작
+  ↓
+sandbox.ts: "샌드박스 설정이 있나?"
+  ├── YES → CLI 프로세스를 컨테이너/Seatbelt 안에서 재실행
+  │         컨테이너 내부: CLI → LLM → 도구 → 격리 환경 ✅
+  └── NO  → 호스트에서 직접 실행
+```
+
+**핵심**: 도구별 격리가 아니라, CLI 프로세스 전체를 샌드박스 안에서 실행.
+
+### 샌드박스 종류
+
+| 방식     | 환경       | 설정 값        | 특징                                                 |
+| -------- | ---------- | -------------- | ---------------------------------------------------- |
+| Seatbelt | macOS 기본 | `sandbox-exec` | OS 네이티브, 가볍고 빠름. `.sb` 프로파일로 접근 제어 |
+| Docker   | Linux, CI  | `docker`       | 컨테이너 기반, 완전 격리. Dockerfile로 이미지 빌드   |
+| Podman   | Linux      | `podman`       | Docker 대안, rootless 컨테이너                       |
+| 비활성   | 개발       | `false`        | 격리 없음                                            |
+
+### 설정 우선순위
+
+```
+GEMINI_SANDBOX 환경변수
+  ↓ (없으면)
+~/.gemini/settings.json
+  ↓ (없으면)
+프로젝트 .env 파일
+  ↓ (없으면)
+기본값: macOS → Seatbelt, 기타 → 비활성
+```
+
+### Docker 샌드박스 상세
+
+**Dockerfile**은 샌드박스 컨테이너 이미지를 정의:
+
+```dockerfile
+FROM node:20-slim
+# git, python, ripgrep, jq 등 도구 설치
+COPY didim365-agent-cli-*.tgz      # CLI 패키지
+COPY didim365-agent-cli-core-*.tgz # Core 패키지
+RUN npm install -g ...           # 글로벌 설치
+CMD ["didim"]                    # 기본 엔트리포인트
+```
+
+**컨테이너 실행 시 마운트**:
+
+```
+호스트                         → 컨테이너
+$(pwd) (작업 디렉토리)          → /path/inside/container
+~/.gemini (설정)               → /home/node/.gemini
+/tmp                           → /tmp
+gcloud 설정 (있으면)            → /home/node/.config/gcloud
+GOOGLE_APPLICATION_CREDENTIALS  → 동일 경로
+```
+
+**빌드 명령**: `npm run build:sandbox` → `scripts/build_sandbox.js` →
+`docker build`
+
+---
+
+## 5. Build vs Bundle
+
+| 명령                    | 용도     | 도구                      | 결과물                               |
+| ----------------------- | -------- | ------------------------- | ------------------------------------ |
+| `npm run build`         | 개발     | tsc (TypeScript 컴파일러) | `packages/*/dist/` (개별 .js 파일)   |
+| `npm run bundle`        | 배포     | esbuild (번들러)          | `bundle/gemini.js` (~24MB 단일 파일) |
+| `npm run build:sandbox` | 샌드박스 | docker/podman build       | 컨테이너 이미지                      |
+
+### Bundle 상세
+
+esbuild가 모든 패키지를 하나의 실행 파일로 번들:
+
+```
+esbuild.config.js
+  ├── CLI Config:
+  │   Entry: packages/cli/index.ts
+  │   Output: bundle/gemini.js (~24MB)
+  │   External: node-pty, keytar (네이티브 모듈)
+  │
+  └── A2A Server Config:
+      Entry: packages/a2a-server/src/http/server.ts
+      Output: packages/a2a-server/dist/a2a-server.mjs
+```
+
+**배포 경로**:
+
+```
+npm run bundle
+  → bundle/gemini.js 생성
+  → npm publish
+  → 사용자: npm install -g @didim365/agent-cli
+  → /usr/local/bin/didim → bundle/gemini.js
+```
+
+---
+
+## 6. 멀티 LLM 프로바이더 구조
+
+```
+packages/core/src/providers/
+├── index.ts              # 부트스트랩, 프로바이더 팩토리
+├── providerTypes.ts      # 공통 타입 정의
+├── baseAdapter.ts        # 어댑터 기본 클래스
+├── gemini/               # Gemini 프로바이더
+│   ├── geminiAdapter.ts
+│   ├── geminiConverter.ts
+│   └── geminiStreamHandler.ts
+├── claude/               # Claude 프로바이더
+│   ├── claudeAdapter.ts
+│   ├── claudeConverter.ts
+│   └── claudeStreamHandler.ts
+├── openai/               # OpenAI 프로바이더
+│   ├── openaiAdapter.ts
+│   ├── openaiConverter.ts
+│   └── openaiStreamHandler.ts
+└── common/               # 공통 유틸 (에러, 이벤트, 스트림)
+```
+
+모델 이름으로 프로바이더 자동 선택:
+
+- `gemini-*`, `auto`, `pro`, `flash` → Gemini
+- `claude-*` → Claude (Anthropic)
+- `gpt-*`, `o1-*`, `o3-*` → OpenAI
+
+---
+
+## 7. 주요 설정 파일
+
+| 파일                        | 용도                                         |
+| --------------------------- | -------------------------------------------- |
+| `package.json` (root)       | 워크스페이스 정의, 빌드 스크립트, bin 엔트리 |
+| `packages/*/package.json`   | 패키지별 의존성, 빌드 설정                   |
+| `esbuild.config.js`         | 번들 설정 (단일 실행 파일 생성)              |
+| `eslint.config.js`          | 린트 규칙                                    |
+| `tsconfig.json`             | TypeScript 설정                              |
+| `Dockerfile`                | 샌드박스 컨테이너 이미지                     |
+| `bundle/sandbox-macos-*.sb` | macOS Seatbelt 프로파일                      |
+| `CLAUDE.md` / `GEMINI.md`   | AI 에이전트용 프로젝트 컨텍스트              |
+
+---
+
+## 8. 릴리스 채널
+
+| 채널    | npm 태그           | 버전 형식                         | 용도                |
+| ------- | ------------------ | --------------------------------- | ------------------- |
+| Nightly | `nightly`          | `0.8.0-nightly.20250917.d3bf8a3d` | 매일 자동 빌드      |
+| Preview | `preview`          | `0.8.0-preview.0`                 | 테스트용 프리릴리스 |
+| Stable  | `latest`           | `0.7.0`                           | 정식 릴리스         |
+| Patch   | `latest`/`preview` | `0.6.2`, `0.7.0-preview.2`        | 핫픽스              |
+
+**릴리스 스크립트**:
+
+- `scripts/get-release-version.js` — 다음 버전 계산
+- `scripts/prepare-github-release.js` — GitHub Packages용 패키징
+- `scripts/releasing/create-patch-pr.js` — 패치 릴리스 PR 생성
+- `scripts/releasing/patch-comment.js` — PR에 릴리스 결과 코멘트