byuckchon-frontend-cli 1.5.0 → 1.6.0

package/README.md

@@ -91,6 +91,68 @@ bc init
 > 안전망은 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 시작할 때 알아서 준비됩니다.**
@@ -208,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` — 설정
 
@@ -224,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 복귀
 ```
 
 ## 설정 위치
@@ -263,7 +341,8 @@ bc config set-gateway                       # 게이트웨이 해제 (BYOK 모
 - [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 가 실제 파일을 만든다
-- [ ] v1.6.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
+- [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.5.0');
+  .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.5.0",
+  "version": "1.6.0",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {

package/src/ai/systemPrompt.js

@@ -28,6 +28,18 @@ export function buildSystemPrompt({ effective, paths, project }) {
     '     - 자동 생성된 `*.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 색 이름이나 디자인 토큰을 사용.',
+    '',
     '"코드 짜줘" 라는 표현은 채팅창에 코드 블록을 출력하라는 의미가 **아니다**.',
     '항상 툴을 사용해 실제 파일을 만들어라. 채팅에는 진행 상황과 결과 요약만 짧게 적는다.',
     '',
@@ -57,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

@@ -5,6 +5,13 @@ 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 용 툴 정의.
@@ -164,6 +171,91 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
     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:
@@ -232,5 +324,51 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
       },
       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

@@ -133,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 });
   }
 

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;
+}