byuckchon-frontend-cli 1.4.1 → 1.6.0

package/README.md

@@ -62,6 +62,97 @@ bc init
 프로젝트 이름, 프레임워크, **기본 AI 모델, Figma URL, OpenAPI URL** 을 묻고
 새 폴더에 코드 + `bc.config.json` 까지 만들어 줍니다.
 
+### 에이전트 모드 — AI 가 실제 파일을 만들고 고친다 (v1.5+)
+
+`bc chat` 은 더 이상 채팅창에 코드 블록을 출력만 하지 않습니다. **모델이 직접 툴을 호출해서
+파일을 만들고/고칩니다** (Codex CLI / Cursor agent 와 같은 컨셉).
+
+내장된 툴:
+
+| 툴            | 동작                                                   |
+| ------------- | ------------------------------------------------------ |
+| `read_file`   | 프로젝트 내 파일/디렉터리 내용 읽기                     |
+| `list_files`  | 글롭 패턴으로 파일 나열                                 |
+| `search_code` | RAG 인덱스 의미 기반 검색 (인덱스 있어야 함)             |
+| `write_file`  | 새 파일 생성 또는 통째 덮어쓰기                          |
+| `edit_file`   | 유일한 `old_string → new_string` 으로 부분 수정 (안전)  |
+
+모델은 한 턴 안에서 **최대 12 step** 까지 툴을 자유롭게 호출합니다. 일반적인 흐름:
+1. `list_files` 로 `src/api/` 구조 파악
+2. `read_file` 로 기존 모듈 2~3개 읽고 컨벤션 학습
+3. `search_code` 로 fetch 래퍼 / hook 패턴 검색
+4. `write_file` 로 `api/`, `service/`, `hook/`, `schema/`, `types/` 파일들을 한꺼번에 생성
+5. 마지막에 만든 파일 목록과 import 가이드를 짧게 요약
+
+모든 파일 경로는 `bc.config.json` 이 있는 디렉터리(=프로젝트 루트) 하위로만 강제됩니다.
+`../` 이나 절대경로 탈출은 에러로 거부.
+
+> **승인 게이트 (Phase 4 예정):** 지금은 모델이 write/edit 을 호출하면 즉시 디스크에 반영됩니다.
+> 안전망은 git diff. 매 작업 후 `git status` / `git diff` 로 확인하고, 마음에 안 들면 `git checkout .` 으로 되돌리세요.
+> 다음 버전에서 per-file 승인(`y/n/v`) 옵션 추가 예정.
+
+### Figma 연동 — 디자인 → 코드 (v1.6+)
+
+채팅 안에서 모델이 직접 Figma REST API 를 호출해서 디자인 정보를 읽고 컴포넌트/페이지를 만듭니다.
+
+#### 사용자가 한 번만 하는 셋업
+
+```bash
+# 1) Figma → Settings → Personal access tokens → "Generate new token"
+#    Read 권한만 있으면 충분 (file 읽기 / image export 둘 다 read 로 됨)
+
+# 2) 토큰을 .env 에 박기 (gitignore 됨)
+echo "FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxx" >> .env
+
+# 3) bc.config.json 의 design.figma 에 파일/노드 URL 박기 (bc adopt 시점에 입력하거나 직접 편집)
+```
+
+`bc.config.json` 예시:
+
+```json
+{
+  "design": {
+    "figma": "https://www.figma.com/design/ABC123/Marketd-Admin?node-id=2-105",
+    "figmaTokenEnv": "FIGMA_TOKEN"
+  }
+}
+```
+
+#### 디자이너 협업이 필요한 부분
+
+| 디자이너 측 작업                       | 왜 필요?                                                  |
+| --------------------------------------- | --------------------------------------------------------- |
+| 프레임/컴포넌트에 **의미 있는 이름**     | `Frame 21` 이 아니라 `Card/Product/Sold-out` 처럼 의미별로 — AI 가 이름으로 컴포넌트 이름과 variant 를 추론합니다. |
+| **Auto layout** 적용                    | 안 쓰면 픽셀 좌표만 떨어져 `position: absolute` 코드가 나옵니다. Auto layout 이면 자동으로 `flex`/`gap` 변환. |
+| **로컬 스타일** 등록 (color/text)        | "Brand/Primary" 같은 스타일을 등록해두면 `fetch_figma_styles` 로 디자인 토큰을 일괄 추출해서 Tailwind 테마로 바로 박을 수 있어요. |
+| **Components** 화 (♦ 마름모 아이콘)     | 반복 UI 가 component 면 모델이 "이거 디자인 시스템 컴포넌트구나" 인식 → 코드에서도 재사용 컴포넌트를 만듭니다. |
+| frame 별로 **"Copy link to selection"** | 일반 share link 는 파일 전체. 특정 frame URL 을 받아야 AI 가 그것만 정확히 가져옵니다. |
+
+#### 채팅에서 쓰는 법
+
+```text
+you › 새 멤버 카드 컴포넌트 만들어줘. 디자인은 https://www.figma.com/design/.../?node-id=12-34 이거 참고해서.
+
+🔧 fetch_figma("https://www.figma.com/design/.../?node-id=12-34")
+🔧 list_files("src/components/**/Card*")
+🔧 read_file("src/components/Card/ProductCard.tsx")
+🆕 생성 src/components/Card/MemberCard/MemberCard.tsx (52 lines)
+🆕 생성 src/components/Card/MemberCard/index.ts (3 lines)
+bc › Auto layout 이 row 였고 padding 12/16 이었어요. MemberCard 만들었습니다.
+     기존 ProductCard 와 같은 폴더 컨벤션을 따랐어요.
+```
+
+내장 Figma 툴:
+
+| 툴                    | 동작                                                          |
+| --------------------- | ------------------------------------------------------------- |
+| `fetch_figma`         | 노드 트리 (autoLayout / fills / text / size / children) 가져오기 |
+| `fetch_figma_image`   | 프레임을 PNG/JPG/SVG 로 export — public asset 으로 저장도 가능 |
+| `fetch_figma_styles`  | 파일의 컬러/타이포 토큰 목록 → 디자인 토큰 generator 만들 때    |
+
+> Figma 응답은 자동으로 압축됩니다 (자식 60개, 깊이 8 까지). 너무 큰 프레임은 더 작은
+> 자식 frame URL 을 줘서 분할 정복하세요.
+
 ### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
 
 `bc.config.json` 의 `api.openapi` 와 코드 인덱스는 **chat 시작할 때 알아서 준비됩니다.**
@@ -179,11 +270,25 @@ Claude / GPT 비전 모델에 멀티파트 메시지로 전달됩니다.
 3. `/paste` — **macOS 한정**, 클립보드의 이미지(예: `Cmd+Shift+4` 스크린샷)를 바로 첨부.
    - 사전에 `brew install pngpaste` 한 번 필요.
 
-### 한글 입력이 안 보일 때
+### 한글 입력이 자꾸 씹힐 때 (v1.6+)
+
+`ink` 의 TextInput 은 macOS 한글 IME 의 조합 단계와 충돌해 글자가 한 박자 늦게 보이거나
+빠뜨려지는 경우가 있습니다 — ink-text-input 의 알려진 한계입니다.
+
+**가장 확실한 해결**: 입력 모드를 plain(readline) 으로 영구 전환
+
+```bash
+bc config set-ui plain    # 글로벌로 plain 모드 고정
+# 한글 입력 안정, 모든 기본 기능 동작 (RAG, OpenAPI, Figma 툴 호출까지)
+# 단, ink 전용 기능 일부 미지원: 슬래시 자동완성 메뉴, 인라인 이미지 첨부
+```
+
+ink 로 다시 돌아오려면:
+```bash
+bc config set-ui ink
+```
 
-ink 가 터미널 커서를 숨겨버려서 macOS 한글 IME 의 조합 미리보기가 안 보이는 이슈가 있었습니다.
-v1.4 부터는 ink 시작 후 커서를 강제로 다시 켜고 가짜 커서를 끄는 방식으로 수정되어 정상 동작해야 합니다.
-혹시 그래도 문제가 보이면 `bc chat --plain` 으로 readline 모드를 쓸 수 있습니다 (TUI 기능은 일부 제한).
+일회성으로 plain 만 쓰고 싶으면 `bc chat --plain`.
 
 ### `bc config` — 설정
 
@@ -195,6 +300,8 @@ 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 set-ui plain                      # 한글 IME 안정 모드
+bc config set-ui ink                        # 풀 TUI 복귀
 ```
 
 ## 설정 위치
@@ -233,6 +340,9 @@ bc config set-gateway                       # 게이트웨이 해제 (BYOK 모
 - [x] Phase 3b: `bc gen api-types` (OpenAPI → TS 타입), `/paste` 클립보드 이미지, 한글 IME 수정
 - [x] Phase 3c-1: chat 시작 시 인덱스 자동 빌드, OpenAPI 자동 fetch+캐시+시스템 프롬프트 주입
 - [x] v1.4.1 — `deepMerge(null, obj)` TypeError 수정 (`bc adopt` 한 프로젝트에서 모든 명령이 터지던 버그)
+- [x] v1.5.0 — 에이전트 모드 (read/list/search/write/edit 툴) — AI 가 실제 파일을 만든다
+- [x] v1.6.0 — Figma 툴 (fetch_figma / image / styles), 한글 IME 안정 plain 모드 (`bc config set-ui plain`)
+- [ ] v1.7.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
 - [ ] Phase 3c-2: Figma 실 fetch (URL → 노드 트리 → 컴포넌트 인텐트)
 - [ ] Phase 4: `bc gen component/page` (AST 편집 + 검증 루프), `/apply` diff 미리보기
 

package/bin/index.js

@@ -17,6 +17,7 @@ import {
   configSetModelCommand,
   configSetKeyCommand,
   configSetGatewayCommand,
+  configSetUiCommand,
 } from '../src/commands/config.js';
 
 // 프로젝트 .env 가 있으면 자동 로드 (ANTHROPIC_API_KEY, OPENAI_API_KEY 등).
@@ -27,7 +28,7 @@ const program = new Command();
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.4.1');
+  .version('1.6.0');
 
 program
   .command('init')
@@ -128,6 +129,13 @@ cfg
     await configSetGatewayCommand(url);
   });
 
+cfg
+  .command('set-ui <mode>')
+  .description('chat 입력 모드: ink (풀 TUI) | plain (readline — 한글 IME 안정)')
+  .action(async (mode) => {
+    await configSetUiCommand(mode);
+  });
+
 program.exitOverride((err) => {
   if (
     err.code === 'commander.help' ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {

package/src/ai/systemPrompt.js

@@ -10,9 +10,44 @@ import { CONFIG_PATHS } from '../config/index.js';
  */
 export function buildSystemPrompt({ effective, paths, project }) {
   const lines = [
-    '너는 Byuckchon 프론트엔드 팀의 페어 프로그래밍 AI 다.',
-    '한국어로 친근하고 간결하게 답한다. 코드 답변은 마크다운 코드블록(언어 태그 포함)으로 준다.',
-    '추측 대신 모르면 모른다고 말한다. 파일 경로를 언급할 때는 백틱으로 감싼다.',
+    '너는 Byuckchon 프론트엔드 팀의 페어 프로그래밍 AI 이자 **에이전트** 다.',
+    '한국어로 친근하고 간결하게 답한다. 파일 경로는 백틱으로 감싼다.',
+    '추측 대신 모르면 모른다고 말한다.',
+    '',
+    '## 작업 방식 (중요)',
+    '너는 채팅에 코드를 출력하는 게 아니라, **툴을 호출해서 실제로 파일을 만들고 고친다.**',
+    '코드를 작성/수정해달라는 요청을 받으면 다음 순서를 지킨다:',
+    '  1) `list_files` / `read_file` / `search_code` 로 **기존 컨벤션을 먼저 학습**한다.',
+    '     - 비슷한 도메인의 폴더 구조, 파일 이름, import 순서, barrel(`index.ts`) 패턴, ',
+    '       에러 처리 방식, 상태관리/쿼리 패턴 등을 그대로 따라간다.',
+    '     - "기존 api 폴더 참고해서" 같은 요청을 받으면 그 폴더를 list_files 로 훑고',
+    '       대표 파일 2~3개를 read_file 로 반드시 읽는다.',
+    '  2) 필요한 파일을 `write_file` (신규/덮어쓰기) 또는 `edit_file` (부분 수정) 로 **직접 만든다**.',
+    '     - 한 번의 요청에 여러 파일(예: api / service / hook / type / zod schema) 이 필요하면',
+    '       모두 차례로 생성한다. 사용자가 명시하지 않아도 같이 만들 때가 적절하면 만든다.',
+    '     - 자동 생성된 `*.gen.ts` 가 있다면 거기서 타입을 import 해서 재정의를 피한다.',
+    '  3) 마지막으로 **만든 파일 목록과 다음 액션(어디서 import 하면 되는지 등)** 을 한국어로 짧게 요약.',
+    '',
+    '## Figma 작업 (디자인 → 코드)',
+    '사용자가 Figma 링크를 던지거나 "디자인대로 만들어줘" 같은 요청을 하면:',
+    '  1) `fetch_figma(url)` 로 디자인 트리를 받는다. 노드의 name, autoLayout, fills, text, size 를 학습.',
+    '  2) 필요하면 `fetch_figma_styles(url)` 로 컬러/타이포 토큰을 받아 Tailwind config 또는 theme 변수에 반영.',
+    '  3) `list_files` 로 기존 UI 컴포넌트 폴더 구조를 보고, 같은 컨벤션 따라 `write_file` 로 생성.',
+    '  4) Figma `INSTANCE` (= 디자인 시스템 컴포넌트) 가 보이면 기존 코드의 동일 컴포넌트를 ',
+    '     `search_code` 로 찾아 재사용한다. 없으면 컴포넌트부터 생성.',
+    '  5) 픽셀 좌표(absoluteBoundingBox) 보다 **autoLayout** 우선. autoLayout 이 있으면',
+    '     `flex direction={row|col} gap-x` 패턴으로 짠다. 없으면 디자이너에게 ',
+    '     "Auto layout 으로 정리해달라" 고 요청하라고 안내.',
+    '  6) 색은 가능하면 fills 의 raw rgba 대신 Tailwind 색 이름이나 디자인 토큰을 사용.',
+    '',
+    '"코드 짜줘" 라는 표현은 채팅창에 코드 블록을 출력하라는 의미가 **아니다**.',
+    '항상 툴을 사용해 실제 파일을 만들어라. 채팅에는 진행 상황과 결과 요약만 짧게 적는다.',
+    '',
+    '## 안전 규칙',
+    '- 절대 프로젝트 루트 밖을 읽거나 쓰지 않는다.',
+    '- 기존 파일을 덮어쓸 때는 먼저 `read_file` 로 현재 내용을 보고, 의도된 덮어쓰기인지 확인.',
+    '- 큰 변경은 `edit_file` 여러 번이 안전. 통째 덮어쓰기는 새 파일이거나 작은 파일에만.',
+    '- 코드 컨벤션이 모호하면 사용자에게 한 번 물어볼 것 (툴 호출 멈추고 메시지로).',
   ];
 
   const stack = describeStack(project);
@@ -34,7 +69,13 @@ export function buildSystemPrompt({ effective, paths, project }) {
       }\``,
     );
   }
-  if (project?.design?.figma) meta.push(`- Figma: ${project.design.figma}`);
+  if (project?.design?.figma) {
+    meta.push(`- Figma: ${project.design.figma}`);
+    meta.push(
+      '  (Figma 작업 요청을 받으면 fetch_figma 툴로 디자인을 먼저 읽고, ' +
+        '필요하면 fetch_figma_styles 로 토큰을 가져와 코드를 짠다.)',
+    );
+  }
   if (project?.api?.openapi) meta.push(`- OpenAPI: ${project.api.openapi}`);
   if (project?.api?.baseUrl) meta.push(`- API base URL: ${project.api.baseUrl}`);
   if (effective?.model) meta.push(`- 사용 모델: ${effective.model}`);

package/src/ai/tools.js

@@ -0,0 +1,374 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+import { tool } from 'ai';
+
+import { searchIndex } from '../indexer/search.js';
+import {
+  fetchFromUrl as fetchFigmaFromUrl,
+  fetchImageUrls as fetchFigmaImageUrls,
+  fetchStyles as fetchFigmaStyles,
+} from '../figma/api.js';
+import { simplifyFetchNodes } from '../figma/simplify.js';
+import { parseFigmaUrl } from '../figma/url.js';
+
+/**
+ * Agentic chat 용 툴 정의.
+ *
+ * 설계 원칙:
+ *  - **모든 파일 경로는 projectRoot 하위로 강제** (탈출 시도는 에러).
+ *  - read/list/search 는 always-allow (안전).
+ *  - write/edit 는 `safeWrite` 가 디스크에 쓰고 onWrite 콜백으로 UI 에 알린다.
+ *    승인 게이트를 추후 끼우려면 onWrite 안에서 await 로 막으면 된다.
+ *  - 모든 결과는 plain JSON 으로 돌려준다 (모델이 다시 추론하기 좋게).
+ *
+ * 사용:
+ *   const tools = buildTools({ projectRoot, effective, onEvent });
+ *   streamText({ tools, stopWhen: stepCountIs(12), ... });
+ */
+export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
+  const root = path.resolve(projectRoot);
+
+  function safePath(p) {
+    if (!p || typeof p !== 'string') {
+      throw new Error('path 가 비어있습니다');
+    }
+    const abs = path.isAbsolute(p) ? path.resolve(p) : path.resolve(root, p);
+    const rel = path.relative(root, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`프로젝트 루트(${root}) 밖의 경로는 접근할 수 없습니다: ${p}`);
+    }
+    return { abs, rel: rel || '.' };
+  }
+
+  async function readFile({ path: p }) {
+    const { abs, rel } = safePath(p);
+    let stat;
+    try {
+      stat = await fs.stat(abs);
+    } catch {
+      return { ok: false, error: `파일이 존재하지 않습니다: ${rel}` };
+    }
+    if (stat.isDirectory()) {
+      const entries = await fs.readdir(abs, { withFileTypes: true });
+      return {
+        ok: true,
+        kind: 'directory',
+        path: rel,
+        entries: entries.map((e) => (e.isDirectory() ? e.name + '/' : e.name)),
+      };
+    }
+    if (stat.size > 256 * 1024) {
+      return { ok: false, error: `파일이 너무 큽니다 (${stat.size}B). 256KB 이하만 지원.` };
+    }
+    const content = await fs.readFile(abs, 'utf8');
+    return { ok: true, kind: 'file', path: rel, lines: content.split('\n').length, content };
+  }
+
+  async function listFiles({ pattern = '**/*', limit = 100 }) {
+    const matches = await fg(pattern, {
+      cwd: root,
+      ignore: ['node_modules/**', 'dist/**', 'build/**', '.next/**', '.bc/**', '.git/**'],
+      onlyFiles: false,
+      dot: false,
+      followSymbolicLinks: false,
+    });
+    const truncated = matches.length > limit;
+    return {
+      ok: true,
+      total: matches.length,
+      truncated,
+      matches: matches.slice(0, limit),
+    };
+  }
+
+  async function searchCode({ query, k = 8 }) {
+    try {
+      const res = await searchIndex(query, effective, { topK: Math.min(20, Math.max(1, k)), minScore: 0.15 });
+      if (!res.ok) {
+        return { ok: false, error: res.reason ?? 'index 없음 — /index 로 빌드하라고 안내할 것' };
+      }
+      return {
+        ok: true,
+        hits: res.results.map((r) => ({
+          file: r.chunk.file,
+          range: `${r.chunk.startLine}-${r.chunk.endLine}`,
+          score: Number(r.score.toFixed(3)),
+          snippet: r.chunk.text.slice(0, 1200),
+        })),
+      };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
+  async function writeFile({ path: p, content }) {
+    const { abs, rel } = safePath(p);
+    let existed = false;
+    let prevContent = '';
+    try {
+      prevContent = await fs.readFile(abs, 'utf8');
+      existed = true;
+    } catch {
+      /* 새 파일 */
+    }
+    if (existed && prevContent === content) {
+      onEvent({ kind: 'write_skipped', path: rel, reason: '동일' });
+      return { ok: true, path: rel, action: 'noop', reason: '내용 동일' };
+    }
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, content, 'utf8');
+    onEvent({
+      kind: existed ? 'write_overwritten' : 'write_created',
+      path: rel,
+      lines: content.split('\n').length,
+      bytes: Buffer.byteLength(content, 'utf8'),
+    });
+    return {
+      ok: true,
+      path: rel,
+      action: existed ? 'overwritten' : 'created',
+      lines: content.split('\n').length,
+    };
+  }
+
+  async function editFile({ path: p, old_string, new_string }) {
+    const { abs, rel } = safePath(p);
+    let content;
+    try {
+      content = await fs.readFile(abs, 'utf8');
+    } catch {
+      return { ok: false, error: `편집할 파일이 없습니다: ${rel}` };
+    }
+    if (typeof old_string !== 'string' || old_string.length === 0) {
+      return { ok: false, error: 'old_string 이 비어있습니다' };
+    }
+    // 정확 일치 횟수 계산
+    let count = 0;
+    let idx = 0;
+    while ((idx = content.indexOf(old_string, idx)) !== -1) {
+      count++;
+      idx += old_string.length;
+    }
+    if (count === 0) {
+      return { ok: false, error: `old_string 을 ${rel} 에서 찾지 못했습니다. 주변 라인을 더 포함해서 다시 시도.` };
+    }
+    if (count > 1) {
+      return {
+        ok: false,
+        error: `old_string 이 ${rel} 에 ${count}번 등장합니다. 더 많은 컨텍스트로 유일해지게 만들어 주세요.`,
+      };
+    }
+    const updated = content.replace(old_string, new_string);
+    await fs.writeFile(abs, updated, 'utf8');
+    onEvent({
+      kind: 'edit',
+      path: rel,
+      removed: old_string.split('\n').length,
+      added: new_string.split('\n').length,
+    });
+    return { ok: true, path: rel, action: 'edited' };
+  }
+
+  // ─────────── Figma 툴 ───────────
+
+  async function fetchFigma({ url, depth = 4 }) {
+    try {
+      const result = await fetchFigmaFromUrl({ url, effective, depth });
+      if (result.kind === 'file') {
+        return {
+          ok: true,
+          kind: 'file_summary',
+          file: result.summary.name,
+          pages: result.summary.pages,
+          hint:
+            'node-id 가 없는 파일 링크입니다. 디자이너에게 특정 frame 의 ' +
+            '"Copy link to selection" 을 받아오면 더 정확한 코드 생성 가능.',
+        };
+      }
+      const simple = simplifyFetchNodes(result.raw);
+      return {
+        ok: true,
+        kind: 'nodes',
+        fileKey: result.fileKey,
+        nodeId: result.nodeId,
+        documents: simple.documents,
+        components: simple.components,
+        styles: simple.styles,
+      };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err), status: err?.status };
+    }
+  }
+
+  async function fetchFigmaImage({ url, format = 'png', scale = 2, savePath }) {
+    try {
+      const parsed = parseFigmaUrl(url);
+      if (!parsed?.nodeId) {
+        return { ok: false, error: 'node-id 가 있는 frame 링크가 필요합니다.' };
+      }
+      const images = await fetchFigmaImageUrls({
+        fileKey: parsed.fileKey,
+        nodeIds: [parsed.nodeId],
+        format,
+        scale,
+        effective,
+      });
+      const imageUrl = images[parsed.nodeId];
+      if (!imageUrl) {
+        return { ok: false, error: 'Figma 가 이미지 URL 을 돌려주지 않음' };
+      }
+      if (savePath) {
+        const { abs, rel } = safePath(savePath);
+        const res = await fetch(imageUrl);
+        const buf = Buffer.from(await res.arrayBuffer());
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, buf);
+        onEvent({ kind: 'write_created', path: rel, bytes: buf.byteLength });
+        return { ok: true, savedTo: rel, bytes: buf.byteLength, format };
+      }
+      return { ok: true, url: imageUrl, format, expiresInSeconds: 60 * 60 * 24 * 14 };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
+  async function fetchFigmaStylesTool({ url }) {
+    try {
+      const parsed = parseFigmaUrl(url);
+      if (!parsed) return { ok: false, error: 'Figma URL 형식이 아닙니다.' };
+      const styles = await fetchFigmaStyles({ fileKey: parsed.fileKey, effective });
+      // 모델이 디자인 토큰을 만들 때 쓸 수 있도록 styleType 별로 그룹.
+      const grouped = {};
+      for (const s of styles) {
+        const t = s.style_type ?? s.styleType ?? 'OTHER';
+        (grouped[t] ??= []).push({
+          name: s.name,
+          description: s.description ?? '',
+          key: s.key,
+          nodeId: s.node_id ?? s.nodeId,
+        });
+      }
+      return { ok: true, fileKey: parsed.fileKey, total: styles.length, grouped };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
+  return {
+    read_file: tool({
+      description:
+        '프로젝트 안의 파일이나 디렉터리 내용을 읽는다. 코드 짜기 전에 반드시 기존 코드 컨벤션을 먼저 읽어볼 것.',
+      inputSchema: {
+        type: 'object',
+        properties: { path: { type: 'string', description: '프로젝트 루트 기준 상대 경로' } },
+        required: ['path'],
+        additionalProperties: false,
+      },
+      execute: readFile,
+    }),
+    list_files: tool({
+      description:
+        '글롭 패턴으로 파일을 나열. 폴더 구조 파악, 비슷한 모듈 위치 찾기에 사용. 예: "src/api/**/*.ts"',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', default: '**/*' },
+          limit: { type: 'number', default: 100 },
+        },
+        additionalProperties: false,
+      },
+      execute: listFiles,
+    }),
+    search_code: tool({
+      description:
+        '코드베이스를 의미 기반(임베딩)으로 검색. "fetch 래퍼 패턴", "useQuery hook 컨벤션" 같이 자연어로 찾기. 인덱스가 없으면 에러.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+          k: { type: 'number', default: 8 },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      execute: searchCode,
+    }),
+    write_file: tool({
+      description:
+        '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          content: { type: 'string' },
+        },
+        required: ['path', 'content'],
+        additionalProperties: false,
+      },
+      execute: writeFile,
+    }),
+    edit_file: tool({
+      description:
+        '기존 파일에서 old_string 을 찾아 new_string 으로 정확히 1번 치환. old_string 은 파일 안에서 유일해지도록 충분한 컨텍스트(앞뒤 줄) 를 포함시킬 것. 여러 번 등장하면 에러로 거부.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          old_string: { type: 'string' },
+          new_string: { type: 'string' },
+        },
+        required: ['path', 'old_string', 'new_string'],
+        additionalProperties: false,
+      },
+      execute: editFile,
+    }),
+    fetch_figma: tool({
+      description:
+        'Figma 노드 트리(컴포넌트/프레임/페이지) 를 읽는다. URL 에 node-id 가 있으면 그 frame 의 ' +
+        '간소화된 디자인 정보(autoLayout, fills, text, size, children 등) 를 반환. ' +
+        '없으면 파일 페이지 목록만. 컴포넌트/페이지 생성 요청을 받으면 이 툴을 먼저 호출해서 ' +
+        '디자인 의도를 학습한 뒤 코드를 짠다.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'Figma share/copy link' },
+          depth: { type: 'number', default: 4, description: '노드 트리 탐색 깊이 (1-8)' },
+        },
+        required: ['url'],
+        additionalProperties: false,
+      },
+      execute: fetchFigma,
+    }),
+    fetch_figma_image: tool({
+      description:
+        'Figma 프레임을 PNG/JPG/SVG 이미지로 export. savePath 를 주면 프로젝트 폴더 안에 파일로 저장 ' +
+        '(스토리북 배경, public asset 등). 안 주면 임시 URL 만 반환.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          url: { type: 'string' },
+          format: { type: 'string', enum: ['png', 'jpg', 'svg', 'pdf'], default: 'png' },
+          scale: { type: 'number', default: 2 },
+          savePath: { type: 'string' },
+        },
+        required: ['url'],
+        additionalProperties: false,
+      },
+      execute: fetchFigmaImage,
+    }),
+    fetch_figma_styles: tool({
+      description:
+        'Figma 파일의 로컬 스타일(컬러/타이포/이펙트 토큰) 목록을 가져온다. 디자인 토큰 추출 / ' +
+        'Tailwind 테마 설정 / theme.ts 생성 시 사용.',
+      inputSchema: {
+        type: 'object',
+        properties: { url: { type: 'string' } },
+        required: ['url'],
+        additionalProperties: false,
+      },
+      execute: fetchFigmaStylesTool,
+    }),
+  };
+}

package/src/commands/adopt.js

@@ -141,6 +141,13 @@ export async function adoptCommand(opts = {}) {
   if (!process.env.ANTHROPIC_API_KEY) {
     console.log(chalk.dim('    bc config set-key anthropic    # API 키 등록'));
   }
+  if (next.design.figma && !process.env.FIGMA_TOKEN) {
+    console.log(
+      chalk.dim(
+        '    .env 에 FIGMA_TOKEN=figd-... 추가  # https://www.figma.com/settings 에서 발급',
+      ),
+    );
+  }
   console.log(chalk.dim('    bc chat                        # 이 프로젝트 컨텍스트로 대화'));
   console.log();
 }

package/src/commands/chat.js

@@ -1,13 +1,16 @@
 import process from 'node:process';
 
 import chalk from 'chalk';
-import { streamText } from 'ai';
+import { streamText, stepCountIs } from 'ai';
+
+import path from 'node:path';
 
 import { loadEffectiveConfig } from '../config/index.js';
 import { resolveModel } from '../ai/provider.js';
 import { TokenMeter } from '../ai/tokenMeter.js';
 import { buildSystemPrompt } from '../ai/systemPrompt.js';
 import { findModel } from '../ai/models.js';
+import { buildTools } from '../ai/tools.js';
 import {
   createSession,
   saveSession,
@@ -130,8 +133,11 @@ export async function chatCommand(opts = {}) {
   await saveSession(session); // 빈 파일이라도 디스크에 만들어둠
 
   // ink 는 stdin/stdout 둘 다 TTY 이어야 정상 동작.
+  // - --plain 플래그가 명시되거나 비-TTY 면 readline 폴백.
+  // - 글로벌 ui.mode 가 "plain" 이면 한글 IME 가 깨지는 케이스를 자동 회피.
   const isTTY = process.stdin.isTTY && process.stdout.isTTY;
-  if (!isTTY || opts.plain) {
+  const wantPlain = opts.plain || cfg.global?.ui?.mode === 'plain';
+  if (!isTTY || wantPlain) {
     return runReadlineFallback({ cfg, resolved, system, session, openapiInfo });
   }
 
@@ -189,15 +195,39 @@ async function runInkApp({ cfg, resolved, system, session, openapiInfo }) {
 
 async function runOnce({ cfg, resolved, system, prompt }) {
   const meter = new TokenMeter(resolved.meta, cfg.effective.limits);
+  const projectRoot = cfg.paths.projectFile
+    ? path.dirname(cfg.paths.projectFile)
+    : process.cwd();
+  const tools = buildTools({
+    projectRoot,
+    effective: cfg.effective,
+    onEvent: (ev) => {
+      const label =
+        ev.kind === 'write_created'
+          ? '🆕'
+          : ev.kind === 'write_overwritten'
+            ? '✏️ '
+            : ev.kind === 'edit'
+              ? '✏️ '
+              : '·';
+      console.log(chalk.dim(`  ${label} ${ev.path}`));
+    },
+  });
   const result = streamText({
     model: resolved.model,
     system,
     messages: [{ role: 'user', content: prompt }],
+    tools,
+    stopWhen: stepCountIs(12),
     onError: ({ error }) => {
       console.error(chalk.red('\n  AI 호출 에러: ') + (error?.message ?? error));
     },
   });
-  for await (const delta of result.textStream) process.stdout.write(delta);
+  for await (const part of result.fullStream) {
+    if (part.type === 'text-delta') process.stdout.write(part.text);
+    else if (part.type === 'tool-call')
+      process.stdout.write(chalk.dim(`\n  🔧 ${part.toolName}\n`));
+  }
   process.stdout.write('\n');
   try {
     meter.add(await result.usage);
@@ -257,10 +287,30 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     history.push({ role: 'user', content: line });
     rl.pause();
 
+    const projectRoot = cfg.paths.projectFile
+      ? path.dirname(cfg.paths.projectFile)
+      : process.cwd();
+    const tools = buildTools({
+      projectRoot,
+      effective: cfg.effective,
+      onEvent: (ev) => {
+        const label =
+          ev.kind === 'write_created'
+            ? '🆕 생성'
+            : ev.kind === 'write_overwritten'
+              ? '✏️  덮어씀'
+              : ev.kind === 'edit'
+                ? '✏️  편집'
+                : '·';
+        console.log(chalk.dim(`\n  ${label} ${ev.path}`));
+      },
+    });
     const result = streamText({
       model: resolved.model,
       system,
       messages: history,
+      tools,
+      stopWhen: stepCountIs(12),
       onError: ({ error }) => {
         console.error(chalk.red('\n  AI 호출 에러: ') + (error?.message ?? error));
       },
@@ -268,9 +318,13 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     process.stdout.write(chalk.bold.green('\n  bc › '));
     let acc = '';
     try {
-      for await (const delta of result.textStream) {
-        acc += delta;
-        process.stdout.write(delta);
+      for await (const part of result.fullStream) {
+        if (part.type === 'text-delta') {
+          acc += part.text;
+          process.stdout.write(part.text);
+        } else if (part.type === 'tool-call') {
+          process.stdout.write(chalk.dim(`\n  🔧 ${part.toolName}`));
+        }
       }
     } catch (err) {
       console.error('\n' + chalk.red('  스트리밍 중단: ') + (err?.message ?? err));

package/src/commands/config.js

@@ -51,6 +51,12 @@ export async function configShowCommand() {
   console.log(
     `    ${chalk.dim('요청 확인')}    ${eff.effective.limits.confirmAtTokens.toLocaleString()} tokens`,
   );
+  console.log();
+  console.log(chalk.bold('  UI'));
+  console.log(
+    `    ${chalk.dim('chat 입력 모드')}  ${eff.global?.ui?.mode ?? 'ink'} ` +
+      chalk.dim('(plain 으로 두면 한글 IME 안정. bc config set-ui plain)'),
+  );
 
   if (eff.paths.projectFile) {
     console.log();
@@ -130,6 +136,24 @@ export async function configSetKeyCommand(provider, key) {
   console.log(chalk.dim(`    파일: ${CONFIG_PATHS.globalFile} (chmod 600)\n`));
 }
 
+export async function configSetUiCommand(mode) {
+  const allowed = ['ink', 'plain'];
+  if (!allowed.includes(mode)) {
+    console.error(chalk.red(`사용법: bc config set-ui <${allowed.join('|')}>`));
+    console.error(
+      chalk.dim(
+        '  ink   = 풀 TUI (기본). 한글 IME 가 종종 씹히는 환경에서는 plain 권장.\n' +
+          '  plain = readline 폴백. 한글 입력 안정, 슬래시 명령/이미지 미지원.\n',
+      ),
+    );
+    process.exit(1);
+  }
+  const global = await loadGlobalConfig();
+  global.ui = { ...(global.ui ?? {}), mode };
+  await saveGlobalConfig(global);
+  console.log(chalk.green(`\n  ✓ chat 입력 모드를 '${mode}' 로 저장했습니다.\n`));
+}
+
 export async function configSetGatewayCommand(url) {
   const global = await loadGlobalConfig();
   global.ai.gateway = url && url.trim() ? url.trim() : null;

package/src/config/index.js

@@ -20,6 +20,7 @@ const DEFAULT_GLOBAL = {
     apiKeys: {
       // anthropic: 'sk-ant-...',
       // openai: 'sk-...',
+      // figma: 'figd-...'   // 통상 .env(FIGMA_TOKEN) 로 둠
     },
     /** 사내 게이트웨이를 쓰는 경우 base URL. 비우면 BYOK 모드. */
     gateway: null,
@@ -30,6 +31,14 @@ const DEFAULT_GLOBAL = {
     /** 한 요청이 이 토큰을 넘으면 사용자에게 확인. */
     confirmAtTokens: 12_000,
   },
+  ui: {
+    /**
+     * "ink" | "plain"
+     * 한글 IME 가 ink 에서 글자가 씹히면 "plain" 으로 두면 항상 readline 모드로 진입.
+     * --plain 플래그를 매번 안 쳐도 됨.
+     */
+    mode: 'ink',
+  },
 };
 
 /**

package/src/figma/api.js

@@ -0,0 +1,117 @@
+import { parseFigmaUrl } from './url.js';
+
+/**
+ * Figma REST API 클라이언트.
+ *
+ * 인증: Personal Access Token 을 `X-Figma-Token` 헤더로 보냄.
+ * 토큰은 https://www.figma.com/settings 에서 "Personal access tokens" 로 발급.
+ *
+ * effective.figmaToken (또는 process.env[figmaTokenEnv]) 에서 키를 가져옴.
+ */
+const BASE = 'https://api.figma.com/v1';
+
+export class FigmaError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function tokenFromEnv(effective) {
+  // 1) bc.config.json design.figmaTokenEnv 로 지정한 환경변수
+  const envName = effective?.design?.figmaTokenEnv ?? 'FIGMA_TOKEN';
+  return process.env[envName] ?? process.env.FIGMA_TOKEN ?? null;
+}
+
+async function call(pathAndQuery, { token }) {
+  if (!token) {
+    throw new FigmaError(
+      'Figma 토큰이 없습니다. https://www.figma.com/settings 에서 Personal access token 을 발급받고 ' +
+        '`.env` 에 `FIGMA_TOKEN=figd_...` 로 등록하세요.',
+    );
+  }
+  const res = await fetch(BASE + pathAndQuery, {
+    headers: { 'X-Figma-Token': token },
+  });
+  if (!res.ok) {
+    let body = null;
+    try {
+      body = await res.text();
+    } catch {
+      /* noop */
+    }
+    throw new FigmaError(`Figma API ${res.status} ${res.statusText}: ${pathAndQuery}`, {
+      status: res.status,
+      body,
+    });
+  }
+  return res.json();
+}
+
+/** 파일의 상위 메타 (페이지 목록만 — 노드 트리는 안 가져옴). */
+export async function fetchFileSummary({ fileKey, effective }) {
+  const token = tokenFromEnv(effective);
+  const data = await call(`/files/${fileKey}?depth=1`, { token });
+  return {
+    fileKey,
+    name: data.name,
+    lastModified: data.lastModified,
+    pages:
+      data.document?.children?.map((c) => ({
+        id: c.id,
+        name: c.name,
+        type: c.type,
+      })) ?? [],
+  };
+}
+
+/** 특정 노드들의 상세 트리를 가져옴 (가장 자주 쓰는 API). */
+export async function fetchNodes({ fileKey, nodeIds, effective, depth }) {
+  const token = tokenFromEnv(effective);
+  const ids = (Array.isArray(nodeIds) ? nodeIds : [nodeIds])
+    .filter(Boolean)
+    .map(encodeURIComponent)
+    .join(',');
+  const depthQ = depth ? `&depth=${depth}` : '';
+  const data = await call(`/files/${fileKey}/nodes?ids=${ids}${depthQ}`, { token });
+  return data;
+}
+
+/** 노드를 이미지(PNG/JPG/SVG)로 export 하는 임시 URL 을 받아옴 */
+export async function fetchImageUrls({ fileKey, nodeIds, format = 'png', scale = 2, effective }) {
+  const token = tokenFromEnv(effective);
+  const ids = nodeIds.map(encodeURIComponent).join(',');
+  const data = await call(
+    `/images/${fileKey}?ids=${ids}&format=${format}&scale=${scale}`,
+    { token },
+  );
+  // 응답: { images: { "1:2": "https://...", ... } }
+  return data.images ?? {};
+}
+
+/** 파일에 정의된 로컬 스타일 (color/typography/effect/grid) */
+export async function fetchStyles({ fileKey, effective }) {
+  const token = tokenFromEnv(effective);
+  const data = await call(`/files/${fileKey}/styles`, { token });
+  return data.meta?.styles ?? data.styles ?? [];
+}
+
+/** URL 한 줄로 시작하는 헬퍼 — chat 의 툴에서 가장 흔히 쓰임. */
+export async function fetchFromUrl({ url, effective, depth }) {
+  const parsed = parseFigmaUrl(url);
+  if (!parsed) {
+    throw new FigmaError(`Figma URL 형식이 아닙니다: ${url}`);
+  }
+  if (!parsed.nodeId) {
+    // node-id 없으면 파일 요약만
+    return { kind: 'file', summary: await fetchFileSummary({ fileKey: parsed.fileKey, effective }) };
+  }
+  const data = await fetchNodes({
+    fileKey: parsed.fileKey,
+    nodeIds: [parsed.nodeId],
+    effective,
+    depth,
+  });
+  return { kind: 'nodes', fileKey: parsed.fileKey, nodeId: parsed.nodeId, raw: data };
+}

package/src/figma/simplify.js

@@ -0,0 +1,180 @@
+/**
+ * Figma 노드 트리를 LLM 이 읽기 좋게 압축한다.
+ *
+ * Figma 원 응답은 노드 하나에 수십 KB 도 흔하다. 그대로 모델에 넣으면 토큰이 폭발하고
+ * 모델도 중요한 게 뭔지 못 찾는다. 다음 정보만 남긴다:
+ *   - 이름 (= 디자이너의 의도. 컴포넌트/페이지 명명 규칙)
+ *   - 타입 (FRAME, COMPONENT, INSTANCE, TEXT, RECTANGLE, ...)
+ *   - 위치/크기 (필요한 경우만)
+ *   - autoLayout (있으면 flex/gap 변환에 핵심)
+ *   - fills (색)
+ *   - strokes
+ *   - effects (shadow)
+ *   - text 의 경우 글자 + 폰트 사양
+ *   - cornerRadius, padding 같은 자주 쓰는 박스 속성
+ *   - 자식들 (재귀)
+ *
+ * 모델은 이 압축본을 받아서 React/Tailwind/styled JSX 를 생성한다.
+ */
+
+const MAX_CHILDREN = 60;
+const MAX_DEPTH = 8;
+
+function pickColor(paint) {
+  if (!paint || paint.visible === false) return null;
+  if (paint.type === 'SOLID' && paint.color) {
+    const { r, g, b } = paint.color;
+    const a = paint.opacity ?? paint.color.a ?? 1;
+    return {
+      type: 'solid',
+      rgba: `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${Number(a.toFixed(3))})`,
+    };
+  }
+  if (paint.type?.startsWith('GRADIENT')) {
+    return {
+      type: 'gradient',
+      kind: paint.type,
+      stops:
+        paint.gradientStops?.map((s) => ({
+          position: s.position,
+          rgba:
+            s.color &&
+            `rgba(${Math.round(s.color.r * 255)}, ${Math.round(s.color.g * 255)}, ${Math.round(s.color.b * 255)}, ${Number((s.color.a ?? 1).toFixed(3))})`,
+        })) ?? [],
+    };
+  }
+  if (paint.type === 'IMAGE') {
+    return { type: 'image', scaleMode: paint.scaleMode };
+  }
+  return null;
+}
+
+function describeAutoLayout(node) {
+  if (!node.layoutMode || node.layoutMode === 'NONE') return null;
+  return {
+    direction: node.layoutMode === 'HORIZONTAL' ? 'row' : 'column',
+    gap: node.itemSpacing ?? 0,
+    padding: {
+      top: node.paddingTop ?? 0,
+      right: node.paddingRight ?? 0,
+      bottom: node.paddingBottom ?? 0,
+      left: node.paddingLeft ?? 0,
+    },
+    alignItems: node.counterAxisAlignItems,
+    justifyContent: node.primaryAxisAlignItems,
+    wrap: node.layoutWrap === 'WRAP',
+  };
+}
+
+function describeText(node) {
+  if (node.type !== 'TEXT') return null;
+  const s = node.style ?? {};
+  return {
+    characters: node.characters ?? '',
+    fontFamily: s.fontFamily,
+    fontSize: s.fontSize,
+    fontWeight: s.fontWeight,
+    lineHeight: s.lineHeightPx,
+    letterSpacing: s.letterSpacing,
+    textAlign: s.textAlignHorizontal?.toLowerCase(),
+  };
+}
+
+function simplifyNode(node, depth = 0) {
+  if (!node) return null;
+  const out = {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+  };
+
+  if (node.absoluteBoundingBox) {
+    out.size = {
+      w: Math.round(node.absoluteBoundingBox.width),
+      h: Math.round(node.absoluteBoundingBox.height),
+    };
+  }
+
+  const auto = describeAutoLayout(node);
+  if (auto) out.autoLayout = auto;
+
+  if (node.fills?.length) {
+    const fills = node.fills.map(pickColor).filter(Boolean);
+    if (fills.length) out.fills = fills;
+  }
+  if (node.strokes?.length) {
+    const strokes = node.strokes.map(pickColor).filter(Boolean);
+    if (strokes.length) {
+      out.strokes = strokes;
+      out.strokeWeight = node.strokeWeight;
+    }
+  }
+  if (node.cornerRadius != null) out.cornerRadius = node.cornerRadius;
+  if (node.rectangleCornerRadii) out.cornerRadii = node.rectangleCornerRadii;
+  if (node.effects?.length) {
+    out.effects = node.effects.map((e) => ({
+      type: e.type,
+      radius: e.radius,
+      offset: e.offset,
+      color: e.color &&
+        `rgba(${Math.round(e.color.r * 255)}, ${Math.round(e.color.g * 255)}, ${Math.round(e.color.b * 255)}, ${Number((e.color.a ?? 1).toFixed(3))})`,
+    }));
+  }
+  if (node.opacity != null && node.opacity < 1) out.opacity = node.opacity;
+
+  const text = describeText(node);
+  if (text) out.text = text;
+
+  // Component / Instance — 디자인 시스템의 신호. AI 가 재사용 결정하는 단서.
+  if (node.type === 'INSTANCE' && node.componentId) {
+    out.componentRef = node.componentId;
+  }
+
+  if (node.children?.length && depth < MAX_DEPTH) {
+    const kids = node.children.slice(0, MAX_CHILDREN);
+    const truncated = node.children.length > MAX_CHILDREN;
+    out.children = kids
+      .map((c) => simplifyNode(c, depth + 1))
+      .filter(Boolean);
+    if (truncated) out.childrenTruncated = node.children.length - MAX_CHILDREN;
+  }
+
+  return out;
+}
+
+/**
+ * Figma `fetchNodes` 응답을 받아서 LLM 친화적으로 압축.
+ *
+ * @param {object} fetchNodesResponse - Figma API `/v1/files/.../nodes` 결과
+ * @returns {{ documents: Array<simpleNode>, components: Record, styles: Record }}
+ */
+export function simplifyFetchNodes(fetchNodesResponse) {
+  const out = { documents: [], components: {}, styles: {} };
+  const nodes = fetchNodesResponse?.nodes ?? {};
+  for (const [id, payload] of Object.entries(nodes)) {
+    if (!payload?.document) continue;
+    out.documents.push({
+      requestedId: id,
+      ...simplifyNode(payload.document, 0),
+    });
+    if (payload.components) {
+      Object.assign(out.components, payload.components);
+    }
+    if (payload.styles) {
+      Object.assign(out.styles, payload.styles);
+    }
+  }
+  return out;
+}
+
+/** 사람 눈으로 보기 좋은 한 줄 요약 (디버깅/UI 표시용) */
+export function quickSummary(simple) {
+  if (!simple) return '';
+  const parts = [simple.name + ' [' + simple.type + ']'];
+  if (simple.size) parts.push(`${simple.size.w}×${simple.size.h}`);
+  if (simple.autoLayout) parts.push('auto-' + simple.autoLayout.direction);
+  if (simple.children?.length) parts.push(`children=${simple.children.length}`);
+  return parts.join(' · ');
+}
+
+export { simplifyNode };

package/src/figma/url.js

@@ -0,0 +1,41 @@
+/**
+ * Figma URL/링크 파서.
+ *
+ * 지원하는 URL 형태:
+ *   https://www.figma.com/file/{fileKey}/...                     (구버전 share link)
+ *   https://www.figma.com/design/{fileKey}/...                   (신버전, 2023+)
+ *   https://www.figma.com/proto/{fileKey}/...                    (프로토타입)
+ *   ...?node-id=123-456    또는  ...?node-id=123%3A456           (특정 노드)
+ *
+ * Figma 내부 노드 ID 는 "123:456" 인데 URL 에서는 보통 "123-456" 또는 인코딩됨.
+ * API 호출 시엔 "123:456" 으로 다시 변환해야 함.
+ */
+
+const URL_RE = /figma\.com\/(?:file|design|proto)\/([A-Za-z0-9]+)/;
+
+export function parseFigmaUrl(input) {
+  if (!input || typeof input !== 'string') return null;
+  const m = input.match(URL_RE);
+  if (!m) return null;
+  const fileKey = m[1];
+
+  // node-id 추출
+  let nodeId = null;
+  try {
+    const u = new URL(input);
+    const raw = u.searchParams.get('node-id');
+    if (raw) {
+      // "123-456" → "123:456",  "123%3A456" → "123:456"
+      nodeId = decodeURIComponent(raw).replace(/-/g, ':');
+    }
+  } catch {
+    /* not a valid URL — fileKey 만 있으면 그것대로 ok */
+  }
+
+  return { fileKey, nodeId };
+}
+
+/** 디자이너가 도면에서 "Copy link" 한 결과인지 (= node-id 있음) */
+export function hasNode(parsed) {
+  return !!parsed?.nodeId;
+}

package/src/ui/ChatApp.js

@@ -5,17 +5,45 @@ import React, { useEffect, useState, useRef, useCallback } from 'react';
 import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import TextInput from 'ink-text-input';
 import Spinner from 'ink-spinner';
-import { streamText } from 'ai';
+import { streamText, stepCountIs } from 'ai';
 
 import { resolveModel } from '../ai/provider.js';
 import { TokenMeter } from '../ai/tokenMeter.js';
 import { findModel, MODEL_CATALOG } from '../ai/models.js';
 import { toSdkMessages, isImagePath } from '../ai/messageContent.js';
+import { buildTools } from '../ai/tools.js';
 import { searchIndex } from '../indexer/search.js';
 import { loadIndex, buildIndex } from '../indexer/store.js';
 
 const h = React.createElement;
 
+/** 툴 호출의 input 을 채팅 한 줄에 보여줄 수 있게 압축. content 같은 대형 필드는 길이만 표시. */
+function summarizeToolInput(name, input) {
+  if (!input || typeof input !== 'object') return '';
+  switch (name) {
+    case 'read_file':
+    case 'write_file':
+    case 'edit_file':
+      return JSON.stringify(input.path ?? '');
+    case 'list_files':
+      return JSON.stringify(input.pattern ?? '**/*');
+    case 'search_code':
+      return JSON.stringify(input.query ?? '');
+    default:
+      // 일반 케이스 — 너무 긴 필드는 잘라낸다.
+      try {
+        const small = {};
+        for (const [k, v] of Object.entries(input)) {
+          if (typeof v === 'string' && v.length > 60) small[k] = v.slice(0, 60) + '…';
+          else small[k] = v;
+        }
+        return JSON.stringify(small);
+      } catch {
+        return '';
+      }
+  }
+}
+
 /**
  * macOS 클립보드의 이미지(예: 스크린샷)를 임시 파일로 떨궈 절대경로를 돌려준다.
  *
@@ -673,10 +701,45 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
 
     try {
       const sdkMessages = await toSdkMessages(newMessages);
+
+      // 프로젝트 루트 결정: bc.config.json 이 있는 디렉터리, 없으면 cwd.
+      const projectRoot = cfg.paths.projectFile
+        ? path.dirname(cfg.paths.projectFile)
+        : process.cwd();
+
+      // 툴 실행 이벤트는 채팅에 시스템 메시지로 표시 (사용자가 무엇이 일어났는지 보게).
+      const onToolEvent = (ev) => {
+        const labels = {
+          write_created: '🆕 생성',
+          write_overwritten: '✏️  덮어씀',
+          write_skipped: '⏭  스킵',
+          edit: '✏️  편집',
+        };
+        const label = labels[ev.kind] ?? ev.kind;
+        const detail =
+          ev.lines != null
+            ? `(${ev.lines} lines)`
+            : ev.added != null
+              ? `(+${ev.added} / -${ev.removed} lines)`
+              : '';
+        setMessages((m) => [
+          ...m,
+          { role: 'system-info', text: `${label} ${ev.path} ${detail}`.trim() },
+        ]);
+      };
+
+      const tools = buildTools({
+        projectRoot,
+        effective: cfg.effective,
+        onEvent: onToolEvent,
+      });
+
       const result = streamText({
         model: resolved.model,
         system: systemWithContext,
         messages: sdkMessages,
+        tools,
+        stopWhen: stepCountIs(12),
         onError: ({ error }) => {
           replaceWithError('AI 호출 에러: ' + (error?.message ?? String(error)));
         },
@@ -685,13 +748,36 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       setState('streaming');
       let acc = '';
       try {
-        for await (const delta of result.textStream) {
-          acc += delta;
-          setMessages((m) => {
-            const next = [...m];
-            next[assistantIdx] = { role: 'assistant', text: acc, streaming: true };
-            return next;
-          });
+        // fullStream 으로 tool-call / tool-result / text-delta 다 다룸.
+        for await (const part of result.fullStream) {
+          if (part.type === 'text-delta') {
+            acc += part.text;
+            setMessages((m) => {
+              const next = [...m];
+              next[assistantIdx] = { role: 'assistant', text: acc, streaming: true };
+              return next;
+            });
+          } else if (part.type === 'tool-call') {
+            // 모델이 툴을 호출하는 순간 — 한 줄로 표시.
+            const argSummary = summarizeToolInput(part.toolName, part.input);
+            setMessages((m) => [
+              ...m,
+              {
+                role: 'system-info',
+                text: `🔧 ${part.toolName}(${argSummary})`,
+              },
+            ]);
+          } else if (part.type === 'tool-error') {
+            setMessages((m) => [
+              ...m,
+              {
+                role: 'system-error',
+                text: `툴 에러 (${part.toolName ?? '?'}): ${part.error?.message ?? part.error}`,
+              },
+            ]);
+          } else if (part.type === 'error') {
+            replaceWithError('스트림 에러: ' + (part.error?.message ?? String(part.error)));
+          }
         }
       } catch (streamErr) {
         replaceWithError('스트리밍 중단: ' + (streamErr?.message ?? String(streamErr)));
@@ -700,14 +786,26 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       // 에러가 안 났을 때만 final assistant 로 마무리.
       if (!errorText) {
         if (acc.length === 0) {
-          // 응답이 아예 비었지만 onError 도 안 떴다 → finishReason 으로 추적.
+          // 텍스트가 없어도 툴만 호출하고 끝났을 수 있음 — 그건 정상.
+          // finishReason 으로 진짜 비정상인지 분기.
           let reason = 'unknown';
           try {
             reason = await result.finishReason;
           } catch {
             /* noop */
           }
-          replaceWithError(`빈 응답 (finishReason=${reason}). API 키/크레딧/모델을 확인하세요.`);
+          if (reason === 'tool-calls' || reason === 'stop') {
+            // 툴만 호출하고 자연스럽게 멈춤 → placeholder 제거.
+            setMessages((m) => {
+              const next = [...m];
+              if (next[assistantIdx]?.role === 'assistant' && !next[assistantIdx].text) {
+                next.splice(assistantIdx, 1);
+              }
+              return next;
+            });
+          } else {
+            replaceWithError(`빈 응답 (finishReason=${reason}). API 키/크레딧/모델을 확인하세요.`);
+          }
         } else {
           setMessages((m) => {
             const next = [...m];