byuckchon-frontend-cli 1.1.0 → 1.4.0

package/README.md

@@ -1,26 +1,204 @@
 # byuckchon-frontend-cli
 
-[byuckchon](https://www.byuckchon.com) 컨벤션에 맞게 React(Vite) 또는 Next.js(App Router) TypeScript 프로젝트를 생성하는 CLI.
+[byuckchon](https://www.byuckchon.com) 프론트엔드 팀의 **프로젝트 스타터 + AI 어시스턴트** CLI.
+React(Vite) / Next.js(App Router) TypeScript 프로젝트를 만들고, `bc chat` 으로 AI 와 코드 이야기를 나눌 수 있습니다.
 
 ## 요구 사항
 
-- [Node.js](https://nodejs.org/) (LTS 권장)
+- [Node.js](https://nodejs.org/) 18+ (LTS 권장)
+- AI 사용 시: Anthropic 또는 OpenAI API 키
 
-## 사용법
+## 설치
 
 ```bash
-npx byuckchon-frontend-cli
+npm install -g byuckchon-frontend-cli
+# 짧은 alias 도 동시에 설치됨: `bc`
 ```
 
-프로젝트 이름과 프레임워크를 묻는 프롬프트에 따라 답하면, 현재 디렉터리에 새 폴더가 만들어집니다.
+## 명령
 
-생성이 끝나면 안내에 따라 다음을 실행하세요.
+### `bc init` — 새 프로젝트 만들기
 
 ```bash
-cd <프로젝트-이름>
-npm run dev
+bc init
 ```
 
+프로젝트 이름, 프레임워크, **기본 AI 모델, Figma URL, OpenAPI URL** 을 묻고
+새 폴더에 코드 + `bc.config.json` 까지 만들어 줍니다.
+
+### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
+
+`bc.config.json` 의 `api.openapi` 와 코드 인덱스는 **chat 시작할 때 알아서 준비됩니다.**
+즉, 명령을 외울 필요 없이 그냥 `bc` 만 치고 자연어로 일을 시키면 됩니다.
+
+- **OpenAPI**: chat 시작 시 자동 fetch + 1시간 디스크 캐시 → 엔드포인트 요약을 시스템 프롬프트에 박음.
+  - 헤더에 `openapi` 줄로 표시. 캐시 hit 면 `(cached)`, fresh fetch 면 `(live)`.
+- **코드 인덱스**: chat 시작 시 인덱스 파일이 없으면 **백그라운드에서 자동 빌드**.
+  - 빌드 중에는 화면에 `📚 인덱싱 중 ...` 진행 표시. 끝나면 `✓` 메시지 한 줄.
+  - OpenAI 키가 없으면 빌드를 건너뛰고 도움 메시지를 띄움 (Anthropic 은 임베딩 API 미제공).
+- **수동 컨트롤이 필요할 때:**
+
+| 시나리오                                | 명령                                                |
+| --------------------------------------- | --------------------------------------------------- |
+| 인덱스 다시 빌드 (chat 안에서)          | `/index` 또는 `/index rebuild`                       |
+| 인덱스 다시 빌드 (chat 밖에서)          | `bc index` / `bc index --rebuild`                   |
+| 인덱스 상태/검색                         | `bc index status` / `bc index search "토큰 갱신"`    |
+| OpenAPI → `*.gen.ts` 결정론 생성         | `bc gen api-types` (필요할 때만, AI 가 권하기도 함) |
+| RAG 잠시 끄기                            | chat 안에서 `/rag off`                              |
+
+#### 예시 — 진짜로 명령 안 외우고 시키기
+
+`bc.config.json` 에 Swagger URL 만 박혀 있으면:
+
+```text
+you › api/seller 부분 GET~POST 내 api 폴더 구조 참고해서 코드 짜줘
+```
+
+→ 모델이 자동 주입된 OpenAPI 요약 + RAG 로 가져온 `src/api/*` 컨텍스트를 보고
+   해당 프로젝트 컨벤션(예: 기존 fetch 래퍼, axios 인스턴스, TanStack Query 훅 패턴)에 맞춰 코드를 짜 줍니다.
+   타입이 부족하면 모델이 **"`bc gen api-types` 한 번 돌려달라"** 고 직접 안내해 줍니다.
+
+> 비결정론적 코드 생성보다 결정론적인 타입 생성이 안전한 부분(예: `*.gen.ts`) 만 별도 명령으로 빼두고,
+> 컴포넌트/엔드포인트 호출 코드는 채팅으로 처리하는 하이브리드 구조입니다.
+
+#### `bc gen api-types` (선택) — OpenAPI → TS 타입 결정론 생성
+
+```bash
+bc gen api-types                                          # bc.config.json 의 api.openapi 사용
+bc gen api-types --source https://api.dev/openapi.json    # URL 직접
+bc gen api-types --source ./openapi.yaml                  # 로컬 파일
+bc gen api-types --out src/api/types.gen.ts               # 출력 경로 지정 (기본값)
+```
+
+```ts
+import type { paths, components } from '@/api/types.gen';
+
+type ListUsersResponse =
+  paths['/users']['get']['responses']['200']['content']['application/json'];
+type User = components['schemas']['User'];
+```
+
+### `bc adopt` — 기존 프로젝트에 bc 설정만 깔기
+
+```bash
+cd 내-Expo-프로젝트
+bc adopt
+```
+
+`package.json` 과 디렉터리를 스캔해서 **프레임워크/언어/스타일/라우팅/패키지 매니저** 를 자동 감지하고,
+Figma·OpenAPI URL 만 추가로 묻고 `bc.config.json` 만 떨궈줍니다.
+**소스 코드는 절대 건드리지 않습니다.**
+
+지원 감지: Next.js · Expo · Electron · Vite+React · Remix · CRA · 일반 React.
+
+### `bc chat` — AI 와 대화 (ink TUI)
+
+```bash
+bc                                         # 인자 없이도 chat 진입 (제일 짧은 단축키)
+bc start                                   # chat 의 alias
+bc chat                                    # ink 풀 TUI (기본)
+bc chat --model claude-haiku-4             # 이번 세션만 모델 지정
+bc chat --plain                            # 단순 readline 모드
+bc chat --once "useEffect 의존성 배열 누락된 거 어떻게 찾아?"   # 1회성 호출 (CI/스크립트)
+bc chat -c                                 # 가장 최근 세션 이어가기
+bc chat --list-history                     # 저장된 세션 목록
+bc chat --resume 2026-06-19_15-23-45       # 특정 세션 이어가기
+```
+
+**슬래시 명령 자동완성:** 입력창에서 `/` 만 쳐도 사용 가능한 명령이 메뉴로 펼쳐집니다.
+계속 타이핑하면 필터링되고, `↑↓` 로 이동, `Enter` 또는 `Tab` 으로 자동완성, `Esc` 로 취소.
+
+대화 세션은 자동으로 디스크에 저장됩니다:
+
+- 프로젝트 안에서 실행 → `<projectRoot>/.bc/history/<id>.json` (`.bc/` 는 gitignore 됨)
+- 그 외 → `~/.bc/history/<cwd-hash>/<id>.json`
+
+매 턴마다 자동 저장돼서 터미널이 닫히거나 충돌해도 `bc chat -c` 로 바로 복구할 수 있습니다.
+
+TTY 안에서 자동으로 ink 모드로 뜨고, 파이프/CI 같은 비-TTY 환경에서는
+`--plain` 모드로 자동 폴백합니다.
+
+세션 내 슬래시 명령:
+
+| 명령                | 동작                                       |
+| ------------------- | ------------------------------------------ |
+| `/help`             | 도움말                                     |
+| `/clear`            | 대화 컨텍스트 초기화                        |
+| `/model [id]`       | 세션 모델 변경 (인자 없으면 목록)           |
+| `/cost`             | 누적 토큰/비용                              |
+| `/image <path>`     | 다음 메시지에 이미지 첨부 (Vision 모델 권장) |
+| `/paste`            | 클립보드 이미지 첨부 (macOS, `pngpaste` 필요) |
+| `/attachments`      | 현재 첨부 목록                              |
+| `/clear-attach`     | 첨부 비우기                                 |
+| `/index [rebuild]`  | 코드 인덱스 빌드/재빌드 (자동 빌드된 거 갱신) |
+| `/rag on\|off`      | RAG 컨텍스트 주입 즉석 토글                 |
+| `/exit`             | 종료 (`Ctrl+C` 도 가능)                     |
+
+이미지 첨부는 png / jpg / jpeg / gif / webp 만 지원하며,
+Claude / GPT 비전 모델에 멀티파트 메시지로 전달됩니다.
+
+**이미지 첨부 3가지 방법:**
+1. `/image ./shot.png` — 경로 직접
+2. **드래그 & 드롭** — `/image ` 까지 입력 후, Finder 에서 파일을 터미널 위로 끌어다 놓으면 절대경로가 자동 입력됩니다. Enter.
+3. `/paste` — **macOS 한정**, 클립보드의 이미지(예: `Cmd+Shift+4` 스크린샷)를 바로 첨부.
+   - 사전에 `brew install pngpaste` 한 번 필요.
+
+### 한글 입력이 안 보일 때
+
+ink 가 터미널 커서를 숨겨버려서 macOS 한글 IME 의 조합 미리보기가 안 보이는 이슈가 있었습니다.
+v1.4 부터는 ink 시작 후 커서를 강제로 다시 켜고 가짜 커서를 끄는 방식으로 수정되어 정상 동작해야 합니다.
+혹시 그래도 문제가 보이면 `bc chat --plain` 으로 readline 모드를 쓸 수 있습니다 (TUI 기능은 일부 제한).
+
+### `bc config` — 설정
+
+```bash
+bc config show                              # 현재 적용 중인 설정 확인
+bc config set-model                         # 대화형 모델 선택
+bc config set-model claude-sonnet-4-5       # 직접 지정
+bc config set-key anthropic                 # 키 안전 입력 (가려짐)
+bc config set-key anthropic sk-ant-...      # 직접 지정
+bc config set-gateway https://ai.example.com  # 사내 게이트웨이 모드
+bc config set-gateway                       # 게이트웨이 해제 (BYOK 모드)
+```
+
+## 설정 위치
+
+```
+~/.bc/config.json     # 글로벌 — API 키, 기본 모델 (chmod 600)
+<project>/bc.config.json   # 프로젝트별 — Figma/OpenAPI 링크, 기본 모델 강제
+.env                   # 프로젝트 — ANTHROPIC_API_KEY 등 (자동 로드)
+```
+
+우선순위: **환경변수 > 글로벌 키**, **프로젝트 모델 > 글로벌 모델**.
+
+## 지원 모델
+
+| id                  | provider  | 추천 용도                          |
+| ------------------- | --------- | ---------------------------------- |
+| `claude-sonnet-4-5` | anthropic | 기본 — 코드 Q&A, 리팩터, 컴포넌트   |
+| `claude-haiku-4`    | anthropic | 짧은 작업, 커밋 메시지 (저렴)       |
+| `claude-opus-4-5`   | anthropic | 큰 리팩터, 아키텍처 설계 (고가)     |
+| `gpt-5`             | openai    | 일반 코드                          |
+| `gpt-5-mini`        | openai    | 저렴한 OpenAI                      |
+
+## 토큰/비용 안전장치
+
+- 세션 누적이 `limits.warnAtTokens` 를 넘으면 경고 출력.
+- 한 요청 추정 토큰이 `limits.confirmAtTokens` 를 넘으면 확인.
+- BYOK 가 기본 — 외부에서 깔아도 우리 비용은 0.
+- 사내에서는 게이트웨이 모드로 사용량 모니터링 가능.
+
+## 로드맵
+
+- [x] Phase 1: provider 추상화, 글로벌/프로젝트 설정, 스트리밍 REPL
+- [x] Phase 2a: ink 기반 풀 TUI, 이미지 첨부 (`/image`)
+- [x] Phase 2b: 프로젝트 자동 감지(`bc adopt`), 세션 영구 저장(`-c`/`-r`/`--list-history`)
+- [x] Phase 3a: 코드베이스 RAG (`bc index`, `/rag` 토글, 자동 컨텍스트 주입)
+- [x] Phase 3b: `bc gen api-types` (OpenAPI → TS 타입), `/paste` 클립보드 이미지, 한글 IME 수정
+- [x] Phase 3c-1: chat 시작 시 인덱스 자동 빌드, OpenAPI 자동 fetch+캐시+시스템 프롬프트 주입
+- [ ] Phase 3c-2: Figma 실 fetch (URL → 노드 트리 → 컴포넌트 인텐트)
+- [ ] Phase 4: `bc gen component/page` (AST 편집 + 검증 루프), `/apply` diff 미리보기
+
 ## 라이선스
 
 MIT

package/bin/index.js

@@ -1,5 +1,161 @@
 #!/usr/bin/env node
+import { config as loadDotenv } from 'dotenv';
+import { Command } from 'commander';
+import chalk from 'chalk';
 
 import { initCommand } from '../src/commands/init.js';
+import { chatCommand } from '../src/commands/chat.js';
+import { adoptCommand } from '../src/commands/adopt.js';
+import {
+  indexBuildCommand,
+  indexStatusCommand,
+  indexSearchCommand,
+} from '../src/commands/indexCmd.js';
+import { genApiTypesCommand } from '../src/commands/genCmd.js';
+import {
+  configShowCommand,
+  configSetModelCommand,
+  configSetKeyCommand,
+  configSetGatewayCommand,
+} from '../src/commands/config.js';
 
-initCommand();
+// 프로젝트 .env 가 있으면 자동 로드 (ANTHROPIC_API_KEY, OPENAI_API_KEY 등).
+loadDotenv({ quiet: true });
+
+const program = new Command();
+
+program
+  .name('bc')
+  .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
+  .version('1.4.0');
+
+program
+  .command('init')
+  .description('새 프론트엔드 프로젝트 생성 (React/Next.js)')
+  .action(async () => {
+    await initCommand();
+  });
+
+program
+  .command('adopt')
+  .description('기존 프로젝트에 bc 설정만 추가 (Expo/Electron/Next/Vite/CRA 자동 감지)')
+  .option('-f, --force', '기존 bc.config.json 이 있어도 묻지 않고 덮어쓰기')
+  .action(async (opts) => {
+    await adoptCommand(opts);
+  });
+
+const idx = program
+  .command('index')
+  .description('코드베이스 임베딩 인덱스 빌드 (chat 의 RAG 컨텍스트로 사용됨)')
+  .option('--rebuild', '캐시 무시하고 처음부터 다시 빌드')
+  .action(async (opts) => {
+    await indexBuildCommand(opts);
+  });
+
+idx.command('status').description('현재 인덱스 상태').action(async () => {
+  await indexStatusCommand();
+});
+
+idx
+  .command('search <query>')
+  .description('인덱스에서 코드 검색 (디버그용)')
+  .option('-k, --top-k <n>', '상위 K 개', '5')
+  .action(async (query, opts) => {
+    await indexSearchCommand(query, opts);
+  });
+
+const gen = program
+  .command('gen')
+  .description('자동 코드 생성 (OpenAPI → TS 타입 등)');
+
+gen
+  .command('api-types')
+  .description('bc.config.json 의 api.openapi 또는 --source 에서 TS 타입 생성')
+  .option('--source <urlOrPath>', 'OpenAPI URL 또는 로컬 파일 경로')
+  .option('--out <path>', '출력 파일 경로 (기본 src/api/types.gen.ts)')
+  .action(async (opts) => {
+    await genApiTypesCommand(opts);
+  });
+
+// chat 본체와 alias 들을 한 번에 등록하기 위한 헬퍼.
+function registerChatCommand(name, descSuffix = '') {
+  return program
+    .command(name)
+    .description('AI 와 대화하며 코드 묻고/고치기 (ink TUI)' + descSuffix)
+    .option('-m, --model <id>', '이번 세션에 사용할 모델 id')
+    .option('--once <prompt>', 'REPL 없이 한 번만 호출하고 종료')
+    .option('--plain', 'ink TUI 대신 평문 readline 모드')
+    .option('-c, --continue', '가장 최근 세션 이어가기', false)
+    .option('-r, --resume <id>', '특정 세션 id 이어가기')
+    .option('--list-history', '저장된 세션 목록 출력 후 종료', false)
+    .action(async (opts) => {
+      await chatCommand({ ...opts, continueLast: opts.continue });
+    });
+}
+
+registerChatCommand('chat');
+registerChatCommand('start', '  · chat 의 alias');
+
+const cfg = program
+  .command('config')
+  .description('CLI 설정 (모델, API 키, 게이트웨이)');
+
+cfg
+  .command('show')
+  .description('현재 적용 중인 설정 보기')
+  .action(async () => {
+    await configShowCommand();
+  });
+
+cfg
+  .command('set-model [id]')
+  .description('기본 AI 모델 변경 (인자 없으면 대화형)')
+  .action(async (id) => {
+    await configSetModelCommand(id);
+  });
+
+cfg
+  .command('set-key <provider> [key]')
+  .description('API 키 저장 (provider: anthropic | openai). key 생략 시 안전 입력.')
+  .action(async (provider, key) => {
+    await configSetKeyCommand(provider, key);
+  });
+
+cfg
+  .command('set-gateway [url]')
+  .description('사내 AI 게이트웨이 URL 설정 (인자 없으면 해제)')
+  .action(async (url) => {
+    await configSetGatewayCommand(url);
+  });
+
+program.exitOverride((err) => {
+  if (
+    err.code === 'commander.help' ||
+    err.code === 'commander.helpDisplayed' ||
+    err.code === 'commander.version'
+  ) {
+    process.exit(0);
+  }
+  if (err.code === 'commander.missingArgument' || err.code === 'commander.unknownCommand') {
+    console.error(chalk.red('\n  ' + err.message + '\n'));
+    process.exit(1);
+  }
+  throw err;
+});
+
+// 인자 없이 `bc` 만 친 경우엔 chat 으로 자동 진입 (codex CLI 와 같은 UX).
+// 단, --version / --help 같이 명시 플래그가 있으면 commander 가 처리하도록 둔다.
+const NO_ARGS = process.argv.length <= 2;
+
+(async () => {
+  try {
+    if (NO_ARGS) {
+      await chatCommand({});
+      return;
+    }
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    console.error(chalk.red('\n  실행 중 오류: ') + (err?.message ?? err) + '\n');
+    process.exit(1);
+  }
+})();

package/package.json

@@ -1,17 +1,35 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.1.0",
-  "description": "byuckchon frontend CLI for creating React and Next.js projects",
+  "version": "1.4.0",
+  "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
+  "engines": {
+    "node": ">=18.18"
+  },
   "bin": {
-    "byuckchon-frontend-cli": "./bin/index.js"
+    "byuckchon-frontend-cli": "./bin/index.js",
+    "bc": "./bin/index.js"
   },
   "scripts": {
-    "start": "node bin/index.js"
+    "start": "node bin/index.js",
+    "chat": "node bin/index.js chat",
+    "init": "node bin/index.js init",
+    "config": "node bin/index.js config show"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.85",
+    "@ai-sdk/openai": "^3.0.73",
+    "ai": "^6.0.208",
     "chalk": "^5.3.0",
-    "inquirer": "^9.3.0"
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2",
+    "fast-glob": "^3.3.3",
+    "ink": "^7.1.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "inquirer": "^9.3.0",
+    "openapi-typescript": "^7.13.0",
+    "react": "^19.2.7"
   },
   "files": [
     "bin",
@@ -23,8 +41,16 @@
     "byuckchon",
     "frontend",
     "cli",
+    "ai",
+    "claude",
+    "anthropic",
+    "openai",
+    "rag",
+    "ink",
     "react",
-    "next"
+    "next",
+    "expo",
+    "electron"
   ],
   "author": "Byuckchon Frontend Team",
   "license": "MIT",

package/src/ai/messageContent.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const IMAGE_EXT_TO_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+export function isImagePath(p) {
+  if (!p) return false;
+  return Object.keys(IMAGE_EXT_TO_MIME).includes(path.extname(p).toLowerCase());
+}
+
+/**
+ * 파일 경로 → AI SDK 가 받는 image content part 로 변환.
+ *
+ * AI SDK v6 의 multi-modal 메시지 형식:
+ *   { role: 'user', content: [
+ *       { type: 'text', text: '...' },
+ *       { type: 'image', image: <Buffer|base64-data-url|URL> },
+ *   ]}
+ *
+ * Buffer 로 넘기면 SDK 가 알아서 base64 + mime 처리해 준다.
+ */
+export async function imagePartFromFile(filePath) {
+  const abs = path.resolve(filePath);
+  const stat = await fs.stat(abs);
+  if (!stat.isFile()) {
+    const e = new Error(`이미지 파일이 아닙니다: ${filePath}`);
+    e.code = 'BC_NOT_A_FILE';
+    throw e;
+  }
+  if (!isImagePath(abs)) {
+    const e = new Error(
+      `지원 안 하는 확장자: ${path.extname(abs)} (png, jpg, jpeg, gif, webp 만)`,
+    );
+    e.code = 'BC_UNSUPPORTED_IMAGE';
+    throw e;
+  }
+  const buf = await fs.readFile(abs);
+  return {
+    type: 'image',
+    image: buf,
+    // SDK 가 mediaType 을 추론해주기는 하지만 명시적으로 박아둔다.
+    mediaType: IMAGE_EXT_TO_MIME[path.extname(abs).toLowerCase()],
+  };
+}
+
+/**
+ * UI 가 들고 있는 단순한 메시지 형태:
+ *   { role, text, attachments: [{ kind:'image', path, sizeKb }] }
+ * 를 AI SDK 가 받는 messages 배열로 변환한다.
+ *
+ * 반드시 거르는 것들 (이걸 안 거르면 SDK 가 ModelMessage[] 스키마 위반으로 거절한다):
+ *   - 'system-info' / 'system-error' 같은 UI 전용 role (e.g. /help, /clear, 에러 표시)
+ *   - 비어있는 assistant 메시지 (스트리밍 중단, 에러 등으로 텍스트가 한 글자도 없는 경우)
+ *   - 비어있고 첨부도 없는 user 메시지 (방어적 — 정상 입력에선 일어나지 않음)
+ */
+export async function toSdkMessages(uiMessages) {
+  const out = [];
+  for (const m of uiMessages) {
+    if (m.role !== 'user' && m.role !== 'assistant') continue; // UI 전용 role 제거
+    if (m.role === 'assistant' && !m.text?.trim()) continue;   // 빈/실패 응답 제거
+
+    if (m.role === 'user' && m.attachments?.length) {
+      const parts = [];
+      if (m.text) parts.push({ type: 'text', text: m.text });
+      for (const att of m.attachments) {
+        if (att.kind === 'image') {
+          parts.push(await imagePartFromFile(att.path));
+        }
+      }
+      if (parts.length === 0) continue;
+      out.push({ role: 'user', content: parts });
+    } else {
+      if (m.role === 'user' && !m.text?.trim()) continue;
+      out.push({ role: m.role, content: m.text ?? '' });
+    }
+  }
+  return out;
+}

package/src/ai/models.js

@@ -0,0 +1,66 @@
+/**
+ * 지원하는 AI 모델 카탈로그.
+ *
+ * 새 모델/프로바이더를 추가할 때는 이 파일만 수정하면 된다.
+ * id: 사용자가 config 에 저장하는 안정적인 키.
+ * apiModel: 실제 SDK 가 호출할 때 쓰는 모델 식별자.
+ *
+ * 가격은 1M 토큰 기준 USD. 토큰 카운터에서 비용 추정에 쓴다.
+ */
+export const MODEL_CATALOG = [
+  {
+    id: 'claude-sonnet-4-5',
+    label: 'Claude Sonnet 4.5  (권장 · 코드 품질·속도 밸런스)',
+    provider: 'anthropic',
+    apiModel: 'claude-sonnet-4-5',
+    contextWindow: 200_000,
+    pricing: { input: 3, output: 15, cachedInput: 0.3 },
+    tier: 'balanced',
+  },
+  {
+    id: 'claude-haiku-4',
+    label: 'Claude Haiku 4  (저렴 · 짧은 작업·커밋 메시지)',
+    provider: 'anthropic',
+    apiModel: 'claude-haiku-4',
+    contextWindow: 200_000,
+    pricing: { input: 0.8, output: 4, cachedInput: 0.08 },
+    tier: 'fast',
+  },
+  {
+    id: 'claude-opus-4-5',
+    label: 'Claude Opus 4.5  (고성능 · 큰 리팩터·아키텍처)',
+    provider: 'anthropic',
+    apiModel: 'claude-opus-4-5',
+    contextWindow: 200_000,
+    pricing: { input: 15, output: 75, cachedInput: 1.5 },
+    tier: 'powerful',
+  },
+  {
+    id: 'gpt-5',
+    label: 'GPT-5  (OpenAI · 일반 코드)',
+    provider: 'openai',
+    apiModel: 'gpt-5',
+    contextWindow: 400_000,
+    pricing: { input: 5, output: 20, cachedInput: 0.5 },
+    tier: 'balanced',
+  },
+  {
+    id: 'gpt-5-mini',
+    label: 'GPT-5 mini  (OpenAI · 저렴)',
+    provider: 'openai',
+    apiModel: 'gpt-5-mini',
+    contextWindow: 400_000,
+    pricing: { input: 0.5, output: 2, cachedInput: 0.05 },
+    tier: 'fast',
+  },
+];
+
+export const DEFAULT_MODEL_ID = 'claude-sonnet-4-5';
+
+export function findModel(id) {
+  return MODEL_CATALOG.find((m) => m.id === id);
+}
+
+export function modelChoices() {
+  return MODEL_CATALOG.map((m) => ({ name: m.label, value: m.id }));
+}

package/src/ai/provider.js

@@ -0,0 +1,54 @@
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+
+import { findModel } from './models.js';
+
+/**
+ * 설정에서 받은 effective 정보를 가지고 AI SDK 가 바로 쓸 수 있는
+ * `model` 객체를 만들어 돌려준다.
+ *
+ * - gateway 가 있으면 baseURL 로 주입 (사내 프록시 / OpenRouter / LiteLLM 등).
+ * - 키가 없으면 명확한 에러 메시지로 실패 (chat 명령에서 user-friendly 처리).
+ */
+export function resolveModel(effective) {
+  const meta = findModel(effective.model);
+  if (!meta) {
+    const err = new Error(
+      `알 수 없는 모델 '${effective.model}'. \`bc config set-model\` 으로 다시 골라주세요.`,
+    );
+    err.code = 'BC_UNKNOWN_MODEL';
+    throw err;
+  }
+
+  const apiKey = effective.apiKeys?.[meta.provider];
+  if (!apiKey && !effective.gateway) {
+    const envName =
+      meta.provider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY';
+    const err = new Error(
+      `${meta.provider} API 키가 없습니다.\n` +
+        `  - 환경변수 ${envName} 로 넣거나\n` +
+        `  - \`bc config set-key ${meta.provider} <key>\` 로 저장하세요.`,
+    );
+    err.code = 'BC_NO_API_KEY';
+    throw err;
+  }
+
+  if (meta.provider === 'anthropic') {
+    const anthropic = createAnthropic({
+      apiKey: apiKey ?? 'gateway',
+      baseURL: effective.gateway ?? undefined,
+    });
+    return { meta, model: anthropic(meta.apiModel) };
+  }
+  if (meta.provider === 'openai') {
+    const openai = createOpenAI({
+      apiKey: apiKey ?? 'gateway',
+      baseURL: effective.gateway ?? undefined,
+    });
+    return { meta, model: openai(meta.apiModel) };
+  }
+
+  const err = new Error(`지원하지 않는 provider: ${meta.provider}`);
+  err.code = 'BC_UNKNOWN_PROVIDER';
+  throw err;
+}