byuckchon-frontend-cli 1.6.0 → 1.7.0

package/README.md

@@ -74,8 +74,11 @@ bc init
 | `read_file`   | 프로젝트 내 파일/디렉터리 내용 읽기                     |
 | `list_files`  | 글롭 패턴으로 파일 나열                                 |
 | `search_code` | RAG 인덱스 의미 기반 검색 (인덱스 있어야 함)             |
+| `search_openapi` | OpenAPI 스펙에서 엔드포인트 검색 (path/summary/tag) — 큰 스펙도 OK |
+| `get_openapi_endpoint` | 특정 엔드포인트 상세 (params/requestBody/responses, `$ref` 인라인) |
 | `write_file`  | 새 파일 생성 또는 통째 덮어쓰기                          |
 | `edit_file`   | 유일한 `old_string → new_string` 으로 부분 수정 (안전)  |
+| `fetch_figma` / `fetch_figma_image` / `fetch_figma_styles` | Figma 디자인/이미지/토큰 |
 
 모델은 한 턴 안에서 **최대 12 step** 까지 툴을 자유롭게 호출합니다. 일반적인 흐름:
 1. `list_files` 로 `src/api/` 구조 파악
@@ -264,12 +267,20 @@ TTY 안에서 자동으로 ink 모드로 뜨고, 파이프/CI 같은 비-TTY 환
 이미지 첨부는 png / jpg / jpeg / gif / webp 만 지원하며,
 Claude / GPT 비전 모델에 멀티파트 메시지로 전달됩니다.
 
-**이미지 첨부 3가지 방법:**
+**이미지 첨부 3가지 방법:** (ink·plain 모드 모두 지원 — v1.6.1+)
 1. `/image ./shot.png` — 경로 직접
 2. **드래그 & 드롭** — `/image ` 까지 입력 후, Finder 에서 파일을 터미널 위로 끌어다 놓으면 절대경로가 자동 입력됩니다. Enter.
-3. `/paste` — **macOS 한정**, 클립보드의 이미지(예: `Cmd+Shift+4` 스크린샷)를 바로 첨부.
+3. `/paste` — **macOS 한정**, 클립보드의 이미지(예: `Cmd+Shift+4` 스크린샷 또는 Finder 에서 `Cmd+C` 한 이미지)를 바로 첨부.
    - 사전에 `brew install pngpaste` 한 번 필요.
 
+> **터미널에서 `Cmd+V` 로 직접 붙이기는 왜 안 되나?** 터미널 앱은 클립보드의 "이미지 바이트" 를
+> 앱에 전달하지 않고 텍스트만 줍니다 (OS/터미널 공통 제약). 그래서 클립보드 이미지를 붙이려면
+> `/paste` 가 `pngpaste` 로 클립보드를 직접 읽어 첨부합니다 — `Cmd+C` → 입력창에 `/paste` → Enter.
+
+> **썸네일 미리보기:** iTerm2 · kitty · WezTerm 에서는 plain 모드에서 첨부 직후 작은 썸네일이
+> 인라인으로 표시됩니다. 그 외 터미널은 파일명 + 용량만 표시됩니다 (터미널이 이미지 렌더링을
+> 지원하지 않기 때문).
+
 ### 한글 입력이 자꾸 씹힐 때 (v1.6+)
 
 `ink` 의 TextInput 은 macOS 한글 IME 의 조합 단계와 충돌해 글자가 한 박자 늦게 보이거나
@@ -342,7 +353,9 @@ bc config set-ui ink                        # 풀 TUI 복귀
 - [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 미리보기
+- [x] v1.6.1 — 툴 스키마 `jsonSchema()` 래핑 (`schema is not a function` 수정), plain 모드 이미지 첨부(`/image`·`/paste`) + iTerm2/kitty 인라인 썸네일
+- [x] v1.7.0 — OpenAPI 검색 툴 (`search_openapi` / `get_openapi_endpoint`) — 큰 스펙(수백 엔드포인트)에서도 정확한 경로/스키마 조회. 요약도 path 당 1줄로 압축 + 한도 상향
+- [ ] v1.8.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

@@ -28,7 +28,7 @@ const program = new Command();
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.6.0');
+  .version('1.7.0');
 
 program
   .command('init')

package/package.json

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

package/src/ai/clipboard.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * macOS 클립보드의 이미지(스크린샷 등)를 임시 PNG 로 떨궈 절대경로를 돌려준다.
+ *
+ * 터미널 앱은 Cmd+V 로 "이미지 바이트" 를 받지 못한다 (텍스트만 받음). 그래서
+ * 클립보드 이미지를 붙이려면 OS 클립보드를 직접 읽는 외부 도구가 필요하다.
+ *   - macOS: `pngpaste` (brew install pngpaste)
+ *
+ * 다른 OS 거나 도구가 없으면 도움이 되는 에러로 throw.
+ */
+export async function pasteClipboardImage() {
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      '클립보드 이미지 붙여넣기는 현재 macOS 만 지원합니다. 다른 OS 에서는 파일로 저장하고 /image <경로> 를 쓰세요.',
+    );
+  }
+
+  const checkOk = await new Promise((resolve) => {
+    const p = spawn('which', ['pngpaste']);
+    p.on('close', (code) => resolve(code === 0));
+    p.on('error', () => resolve(false));
+  });
+  if (!checkOk) {
+    throw new Error(
+      'pngpaste 가 필요합니다. 설치: `brew install pngpaste`  (Homebrew 가 없으면 https://brew.sh)',
+    );
+  }
+
+  const tmp = path.join(os.tmpdir(), `bc-paste-${Date.now()}.png`);
+  await new Promise((resolve, reject) => {
+    const p = spawn('pngpaste', [tmp]);
+    let stderr = '';
+    p.stderr.on('data', (d) => (stderr += d.toString()));
+    p.on('close', (code) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(
+            '클립보드에 이미지가 없거나 읽을 수 없습니다.' +
+              (stderr ? ' (' + stderr.trim() + ')' : ''),
+          ),
+        );
+    });
+    p.on('error', (e) => reject(e));
+  });
+
+  const stat = await fs.stat(tmp);
+  if (!stat.isFile() || stat.size === 0) {
+    throw new Error('클립보드 이미지 저장 실패 (파일이 비어있음).');
+  }
+  return tmp;
+}
+
+/**
+ * 드래그&드롭 / 붙여넣기로 들어온 경로 문자열을 정리한다.
+ * - 앞뒤 따옴표 제거
+ * - 백슬래시 이스케이프(`\ `) 제거
+ * - 양끝 공백 제거
+ */
+export function cleanDroppedPath(raw) {
+  if (!raw) return '';
+  let s = raw.trim();
+  if (
+    (s.startsWith("'") && s.endsWith("'")) ||
+    (s.startsWith('"') && s.endsWith('"'))
+  ) {
+    s = s.slice(1, -1);
+  }
+  s = s.replace(/\\ /g, ' ');
+  return s.trim();
+}

package/src/ai/imagePreview.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 터미널 인라인 이미지 프리뷰.
+ *
+ * 일반 터미널은 이미지를 못 그린다. 하지만 일부는 자체 프로토콜이 있다:
+ *   - iTerm2  : OSC 1337 ; File=... (base64) BEL
+ *   - kitty   : APC _G ... ST  (kitty graphics protocol)
+ *   - WezTerm : iTerm2 프로토콜 호환
+ *
+ * 지원되면 작은 썸네일을 직접 stdout 에 그려준다. 안 되면 false 반환 → 호출측에서
+ * 파일명/용량만 텍스트로 표시.
+ *
+ * ⚠️ ink TUI 안에서는 re-render 가 escape 시퀀스를 덮어쓰므로 쓰지 않는다.
+ *    readline(plain) 모드처럼 stdout 을 직접 쓰는 곳에서만 사용.
+ */
+export function detectInlineImageSupport() {
+  const term = process.env.TERM ?? '';
+  const prog = process.env.TERM_PROGRAM ?? '';
+  if (prog === 'iTerm.app' || prog === 'WezTerm') return 'iterm2';
+  if (term.includes('kitty') || process.env.KITTY_WINDOW_ID) return 'kitty';
+  return null;
+}
+
+const ESC = '\u001B';
+const BEL = '\u0007';
+
+/** iTerm2 inline image. heightCells 만큼만 차지하도록 제한해 작은 썸네일로. */
+function itermInline(base64, { heightCells = 6 } = {}) {
+  const args = [
+    'inline=1',
+    `height=${heightCells}`,
+    'preserveAspectRatio=1',
+  ].join(';');
+  return `${ESC}]1337;File=${args}:${base64}${BEL}`;
+}
+
+/** kitty graphics — 한 번에 전송(a=T), 직접 표시. */
+function kittyInline(base64) {
+  // kitty 는 4096 바이트 청크로 쪼개야 한다.
+  const CHUNK = 4096;
+  let out = '';
+  let first = true;
+  for (let i = 0; i < base64.length; i += CHUNK) {
+    const piece = base64.slice(i, i + CHUNK);
+    const more = i + CHUNK < base64.length ? 1 : 0;
+    if (first) {
+      out += `${ESC}_Ga=T,f=100,m=${more};${piece}${ESC}\\`;
+      first = false;
+    } else {
+      out += `${ESC}_Gm=${more};${piece}${ESC}\\`;
+    }
+  }
+  return out;
+}
+
+/**
+ * 이미지 파일을 작은 썸네일로 터미널에 그린다.
+ * @returns {Promise<boolean>} 그렸으면 true, 미지원이면 false
+ */
+export async function printInlineThumbnail(filePath, { heightCells = 6 } = {}) {
+  const kind = detectInlineImageSupport();
+  if (!kind) return false;
+  try {
+    const buf = await fs.readFile(path.resolve(filePath));
+    // 너무 크면 프리뷰 스킵 (전송 비용). 2MB 초과면 패스.
+    if (buf.byteLength > 2 * 1024 * 1024) return false;
+    const base64 = buf.toString('base64');
+    if (kind === 'iterm2') {
+      process.stdout.write('  ' + itermInline(base64, { heightCells }) + '\n');
+    } else if (kind === 'kitty') {
+      process.stdout.write('  ' + kittyInline(base64) + '\n');
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/ai/tools.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import fg from 'fast-glob';
-import { tool } from 'ai';
+import { tool, jsonSchema } from 'ai';
 
 import { searchIndex } from '../indexer/search.js';
 import {
@@ -12,6 +12,8 @@ import {
 } from '../figma/api.js';
 import { simplifyFetchNodes } from '../figma/simplify.js';
 import { parseFigmaUrl } from '../figma/url.js';
+import { getCachedOpenApi } from '../openapi/cache.js';
+import { searchEndpoints, getEndpoint } from '../openapi/lookup.js';
 
 /**
  * Agentic chat 용 툴 정의.
@@ -27,9 +29,21 @@ import { parseFigmaUrl } from '../figma/url.js';
  *   const tools = buildTools({ projectRoot, effective, onEvent });
  *   streamText({ tools, stopWhen: stepCountIs(12), ... });
  */
-export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
+export function buildTools({ projectRoot, effective, onEvent = () => {}, openapiSource = null }) {
   const root = path.resolve(projectRoot);
 
+  // OpenAPI 스펙은 한 번만 로드해서 캐시 (큰 파일이라 반복 파싱 비쌈).
+  let _openapiDocPromise = null;
+  function loadOpenApiDoc() {
+    if (!openapiSource) return Promise.resolve(null);
+    if (!_openapiDocPromise) {
+      _openapiDocPromise = getCachedOpenApi(openapiSource)
+        .then((res) => res.doc ?? null)
+        .catch(() => null);
+    }
+    return _openapiDocPromise;
+  }
+
   function safePath(p) {
     if (!p || typeof p !== 'string') {
       throw new Error('path 가 비어있습니다');
@@ -171,6 +185,44 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
     return { ok: true, path: rel, action: 'edited' };
   }
 
+  // ─────────── OpenAPI 툴 ───────────
+
+  async function searchOpenApi({ query, limit = 40 }) {
+    const doc = await loadOpenApiDoc();
+    if (!doc) {
+      return {
+        ok: false,
+        error:
+          'OpenAPI 스펙을 불러올 수 없습니다. bc.config.json 의 api.openapi 가 올바른 JSON 스펙 URL 인지 확인하세요 ' +
+          '(NestJS 는 보통 /api/docs 가 아니라 /api/docs-json).',
+      };
+    }
+    const hits = searchEndpoints(doc, query, { limit });
+    return {
+      ok: true,
+      query,
+      count: hits.length,
+      endpoints: hits.map((e) => ({
+        method: e.method,
+        path: e.path,
+        summary: e.summary,
+        tags: e.tags,
+      })),
+      hint:
+        hits.length === 0
+          ? '매치 없음. 다른 키워드로 재시도하거나, query 를 비워 전체 목록을 받아 path 를 직접 고르세요.'
+          : '상세 스키마가 필요하면 get_openapi_endpoint(path, method) 를 호출하세요.',
+    };
+  }
+
+  async function getOpenApiEndpoint({ path: epPath, method }) {
+    const doc = await loadOpenApiDoc();
+    if (!doc) {
+      return { ok: false, error: 'OpenAPI 스펙을 불러올 수 없습니다.' };
+    }
+    return getEndpoint(doc, epPath, method);
+  }
+
   // ─────────── Figma 툴 ───────────
 
   async function fetchFigma({ url, depth = 4 }) {
@@ -260,31 +312,31 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
     read_file: tool({
       description:
         '프로젝트 안의 파일이나 디렉터리 내용을 읽는다. 코드 짜기 전에 반드시 기존 코드 컨벤션을 먼저 읽어볼 것.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: { path: { type: 'string', description: '프로젝트 루트 기준 상대 경로' } },
         required: ['path'],
         additionalProperties: false,
-      },
+      }),
       execute: readFile,
     }),
     list_files: tool({
       description:
         '글롭 패턴으로 파일을 나열. 폴더 구조 파악, 비슷한 모듈 위치 찾기에 사용. 예: "src/api/**/*.ts"',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           pattern: { type: 'string', default: '**/*' },
           limit: { type: 'number', default: 100 },
         },
         additionalProperties: false,
-      },
+      }),
       execute: listFiles,
     }),
     search_code: tool({
       description:
         '코드베이스를 의미 기반(임베딩)으로 검색. "fetch 래퍼 패턴", "useQuery hook 컨벤션" 같이 자연어로 찾기. 인덱스가 없으면 에러.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           query: { type: 'string' },
@@ -292,13 +344,47 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['query'],
         additionalProperties: false,
-      },
+      }),
       execute: searchCode,
     }),
+    search_openapi: tool({
+      description:
+        '연결된 OpenAPI(Swagger) 스펙에서 엔드포인트를 검색한다. path 일부("admin/inquiries"), ' +
+        '한글 summary("문의"), tag, operationId 어느 걸로도 검색 가능. ' +
+        'API 코드를 짜기 전에 반드시 이 툴로 정확한 경로/메서드를 먼저 확인할 것. ' +
+        '시스템 프롬프트의 요약은 잘려 있을 수 있으므로 "엔드포인트가 안 보인다" 싶으면 이 툴로 찾는다.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '검색어 (path 일부/summary/tag). 비우면 전체 목록' },
+          limit: { type: 'number', default: 40 },
+        },
+        additionalProperties: false,
+      }),
+      execute: searchOpenApi,
+    }),
+    get_openapi_endpoint: tool({
+      description:
+        '특정 엔드포인트의 상세(parameters / requestBody / responses 스키마, $ref 인라인됨) 를 가져온다. ' +
+        'search_openapi 로 찾은 정확한 path 와 method 를 넘긴다. 이 결과로 zod 스키마/타입/요청 함수를 정확히 생성.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '정확한 경로. 예: /api/admin/inquiries' },
+          method: {
+            type: 'string',
+            description: 'GET/POST/... 생략 시 해당 path 의 모든 메서드',
+          },
+        },
+        required: ['path'],
+        additionalProperties: false,
+      }),
+      execute: getOpenApiEndpoint,
+    }),
     write_file: tool({
       description:
         '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           path: { type: 'string' },
@@ -306,13 +392,13 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['path', 'content'],
         additionalProperties: false,
-      },
+      }),
       execute: writeFile,
     }),
     edit_file: tool({
       description:
         '기존 파일에서 old_string 을 찾아 new_string 으로 정확히 1번 치환. old_string 은 파일 안에서 유일해지도록 충분한 컨텍스트(앞뒤 줄) 를 포함시킬 것. 여러 번 등장하면 에러로 거부.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           path: { type: 'string' },
@@ -321,7 +407,7 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['path', 'old_string', 'new_string'],
         additionalProperties: false,
-      },
+      }),
       execute: editFile,
     }),
     fetch_figma: tool({
@@ -330,7 +416,7 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         '간소화된 디자인 정보(autoLayout, fills, text, size, children 등) 를 반환. ' +
         '없으면 파일 페이지 목록만. 컴포넌트/페이지 생성 요청을 받으면 이 툴을 먼저 호출해서 ' +
         '디자인 의도를 학습한 뒤 코드를 짠다.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           url: { type: 'string', description: 'Figma share/copy link' },
@@ -338,14 +424,14 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['url'],
         additionalProperties: false,
-      },
+      }),
       execute: fetchFigma,
     }),
     fetch_figma_image: tool({
       description:
         'Figma 프레임을 PNG/JPG/SVG 이미지로 export. savePath 를 주면 프로젝트 폴더 안에 파일로 저장 ' +
         '(스토리북 배경, public asset 등). 안 주면 임시 URL 만 반환.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           url: { type: 'string' },
@@ -355,19 +441,19 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['url'],
         additionalProperties: false,
-      },
+      }),
       execute: fetchFigmaImage,
     }),
     fetch_figma_styles: tool({
       description:
         'Figma 파일의 로컬 스타일(컬러/타이포/이펙트 토큰) 목록을 가져온다. 디자인 토큰 추출 / ' +
         'Tailwind 테마 설정 / theme.ts 생성 시 사용.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: { url: { type: 'string' } },
         required: ['url'],
         additionalProperties: false,
-      },
+      }),
       execute: fetchFigmaStylesTool,
     }),
   };

package/src/commands/chat.js

@@ -11,6 +11,9 @@ 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 { toSdkMessages, isImagePath, imagePartFromFile } from '../ai/messageContent.js';
+import { pasteClipboardImage, cleanDroppedPath } from '../ai/clipboard.js';
+import { printInlineThumbnail } from '../ai/imagePreview.js';
 import {
   createSession,
   saveSession,
@@ -83,11 +86,15 @@ export async function chatCommand(opts = {}) {
         };
         system =
           baseSystem +
-          '\n\n---\nOpenAPI 스펙 (자동 주입됨, 사용자가 별도로 명령 없이 알아서 사용 가능):\n' +
+          '\n\n---\nOpenAPI 스펙 개요 (아래 목록은 길면 잘려 있을 수 있음):\n' +
           summary +
-          '\n\n사용자가 API 관련 코드를 요청하면 위 스펙을 우선 참조하라. ' +
-          '응답 타입이 필요하면 \`bc gen api-types\` 실행을 권하거나, ' +
-          '이미 \`*.gen.ts\` 가 있으면 그걸 import 해서 쓰라고 안내한다.';
+          '\n\n**중요**: 위 목록은 일부만 보일 수 있다. 사용자가 특정 엔드포인트를 말하거나 ' +
+          '위 목록에서 안 보이면, 추측하지 말고 반드시 `search_openapi(query)` 로 정확한 ' +
+          'path/method 를 검색한 뒤 `get_openapi_endpoint(path, method)` 로 상세 스키마를 ' +
+          '가져와서 zod/타입/요청 함수를 만든다. ' +
+          '예: 사용자가 "inquiries" 라고 하면 search_openapi("inquiries") 로 ' +
+          '`/api/admin/inquiries` 같은 실제 경로를 찾아낸다. ' +
+          '이미 `*.gen.ts` 가 있으면 그걸 import 해서 쓰는 것도 좋다.';
       }
     } catch {
       /* 비정상 URL/네트워크 실패 — 무시하고 계속. */
@@ -201,6 +208,7 @@ async function runOnce({ cfg, resolved, system, prompt }) {
   const tools = buildTools({
     projectRoot,
     effective: cfg.effective,
+    openapiSource: cfg.effective.api?.openapi ?? null,
     onEvent: (ev) => {
       const label =
         ev.kind === 'write_created'
@@ -254,7 +262,46 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
   if (session?.messages?.length) {
     console.log(chalk.dim(`  세션: ${session.id} (${session.messages.length} turns 이어가기)`));
   }
-  console.log(chalk.dim('  /exit 또는 Ctrl+D 로 종료\n'));
+  console.log(
+    chalk.dim('  /image <경로> · /paste(클립보드 이미지) · /clear-attach · /exit\n'),
+  );
+
+  // 다음 메시지에 함께 보낼 이미지 첨부 목록.
+  let pendingAttachments = [];
+
+  const printAttachments = () => {
+    if (!pendingAttachments.length) {
+      console.log(chalk.dim('  첨부 없음.'));
+      return;
+    }
+    console.log(chalk.dim('  현재 첨부:'));
+    for (const a of pendingAttachments) {
+      console.log(chalk.dim(`    - ${path.basename(a.path)} (${a.sizeKb}KB)`));
+    }
+  };
+
+  const addImage = async (rawPath) => {
+    const p = cleanDroppedPath(rawPath);
+    if (!p) {
+      console.log(chalk.red('  사용법: /image <파일 경로>'));
+      return;
+    }
+    if (!isImagePath(p)) {
+      console.log(chalk.red('  지원 확장자: png, jpg, jpeg, gif, webp'));
+      return;
+    }
+    try {
+      const { default: fsp } = await import('node:fs/promises');
+      const stat = await fsp.stat(path.resolve(p));
+      const sizeKb = Math.max(1, Math.round(stat.size / 1024));
+      pendingAttachments.push({ kind: 'image', path: path.resolve(p), sizeKb });
+      console.log(chalk.green(`  📎 첨부: ${path.basename(p)} (${sizeKb}KB)`));
+      // iTerm2 / kitty / WezTerm 이면 작은 썸네일을 바로 보여준다.
+      await printInlineThumbnail(path.resolve(p), { heightCells: 6 });
+    } catch (e) {
+      console.log(chalk.red('  이미지 읽기 실패: ' + (e?.message ?? e)));
+    }
+  };
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -284,7 +331,50 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       rl.close();
       return;
     }
-    history.push({ role: 'user', content: line });
+    // 이미지 첨부 관련 슬래시 명령 — plain 모드에서도 지원.
+    if (line.startsWith('/image')) {
+      await addImage(line.slice('/image'.length).trim());
+      ask();
+      continue;
+    }
+    if (line === '/paste') {
+      try {
+        const file = await pasteClipboardImage();
+        await addImage(file);
+      } catch (e) {
+        console.log(chalk.red('  ' + (e?.message ?? e)));
+      }
+      ask();
+      continue;
+    }
+    if (line === '/attachments') {
+      printAttachments();
+      ask();
+      continue;
+    }
+    if (line === '/clear-attach') {
+      pendingAttachments = [];
+      console.log(chalk.dim('  첨부를 비웠습니다.'));
+      ask();
+      continue;
+    }
+
+    // 일반 메시지 — 첨부가 있으면 멀티모달 content 로 구성.
+    if (pendingAttachments.length) {
+      const parts = [{ type: 'text', text: line }];
+      try {
+        for (const att of pendingAttachments) {
+          parts.push(await imagePartFromFile(att.path));
+        }
+        history.push({ role: 'user', content: parts });
+      } catch (e) {
+        console.log(chalk.red('  첨부 처리 실패: ' + (e?.message ?? e)));
+        history.push({ role: 'user', content: line });
+      }
+      pendingAttachments = [];
+    } else {
+      history.push({ role: 'user', content: line });
+    }
     rl.pause();
 
     const projectRoot = cfg.paths.projectFile
@@ -293,6 +383,7 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     const tools = buildTools({
       projectRoot,
       effective: cfg.effective,
+      openapiSource: cfg.effective.api?.openapi ?? null,
       onEvent: (ev) => {
         const label =
           ev.kind === 'write_created'
@@ -340,7 +431,14 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
 
     // 세션 자동 저장 — readline 모드에서도 끊김 대비.
     if (session) {
-      session.messages = history.map((h) => ({ role: h.role, text: h.content }));
+      session.messages = history.map((h) => {
+        // 멀티모달(content 가 배열) 인 경우 text 파트만 추출해 저장 (이미지 바이트는 세션에 안 남김).
+        if (Array.isArray(h.content)) {
+          const textPart = h.content.find((p) => p.type === 'text');
+          return { role: h.role, text: textPart?.text ?? '[이미지 첨부]' };
+        }
+        return { role: h.role, text: h.content };
+      });
       try {
         await saveSession(session);
       } catch {

package/src/openapi/lookup.js

@@ -0,0 +1,135 @@
+/**
+ * OpenAPI 스펙을 "쿼리" 하는 헬퍼.
+ *
+ * 큰 스펙(수백 개 엔드포인트, 수백 KB) 은 시스템 프롬프트 요약에 다 담을 수도 없고,
+ * 캐시 파일을 통째로 모델에 읽힐 수도 없다(토큰 폭발). 그래서 모델이 필요한 부분만
+ * 골라 가져갈 수 있게 검색/상세조회 함수를 제공한다.
+ *
+ * - searchEndpoints: path/summary/tag/operationId 부분일치로 후보 나열
+ * - getEndpoint:    특정 path(+method) 의 상세를 $ref 해석해서 반환
+ */
+const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+
+/** "#/components/schemas/Foo" → doc.components.schemas.Foo */
+function resolveRef(doc, ref, seen = new Set()) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) return null;
+  const parts = ref.slice(2).split('/');
+  let cur = doc;
+  for (const p of parts) {
+    if (cur == null) return null;
+    cur = cur[p];
+  }
+  return cur ?? null;
+}
+
+/**
+ * 객체 안의 $ref 를 재귀적으로 해석해 인라인한다.
+ * 깊이/순환 방지: maxDepth, seen(ref 경로) 로 컷.
+ */
+function deref(doc, node, { maxDepth = 6, depth = 0, seen = new Set() } = {}) {
+  if (node == null || typeof node !== 'object') return node;
+  if (depth > maxDepth) return node;
+
+  if (node.$ref) {
+    if (seen.has(node.$ref)) return { $ref: node.$ref, note: '(순환 참조 생략)' };
+    const target = resolveRef(doc, node.$ref);
+    if (!target) return node;
+    const nextSeen = new Set(seen);
+    nextSeen.add(node.$ref);
+    return deref(doc, target, { maxDepth, depth: depth + 1, seen: nextSeen });
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((n) => deref(doc, n, { maxDepth, depth: depth + 1, seen }));
+  }
+
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    out[k] = deref(doc, v, { maxDepth, depth: depth + 1, seen });
+  }
+  return out;
+}
+
+/** 모든 엔드포인트의 가벼운 인덱스 (path, method, summary, tags, operationId). */
+export function listEndpoints(doc) {
+  const out = [];
+  for (const [pathStr, methods] of Object.entries(doc?.paths ?? {})) {
+    if (!methods || typeof methods !== 'object') continue;
+    for (const m of METHODS) {
+      const op = methods[m];
+      if (!op || typeof op !== 'object') continue;
+      out.push({
+        method: m.toUpperCase(),
+        path: pathStr,
+        summary: op.summary ?? '',
+        operationId: op.operationId ?? '',
+        tags: op.tags ?? [],
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 부분일치 검색. query 의 각 토큰이 path/summary/operationId/tag 어딘가에
+ * (대소문자 무시) 들어가면 매치. 점수 = 매치한 필드 수 + path 정확 포함 가산점.
+ */
+export function searchEndpoints(doc, query, { limit = 40 } = {}) {
+  const all = listEndpoints(doc);
+  if (!query || !query.trim()) return all.slice(0, limit);
+
+  const tokens = query.toLowerCase().split(/[\s/]+/).filter(Boolean);
+  const scored = [];
+  for (const e of all) {
+    const hay = [
+      e.path.toLowerCase(),
+      e.summary.toLowerCase(),
+      e.operationId.toLowerCase(),
+      e.tags.join(' ').toLowerCase(),
+    ];
+    let score = 0;
+    for (const tok of tokens) {
+      if (hay[0].includes(tok)) score += 3; // path 매치 가중
+      else if (hay.some((h) => h.includes(tok))) score += 1;
+    }
+    if (e.path.toLowerCase().includes(query.toLowerCase())) score += 2;
+    if (score > 0) scored.push({ ...e, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  return scored.slice(0, limit);
+}
+
+/**
+ * 특정 path(+method) 의 상세. $ref 를 인라인해서 request/response 스키마까지 본다.
+ * method 생략 시 그 path 의 모든 메서드 반환.
+ */
+export function getEndpoint(doc, targetPath, method) {
+  const methods = doc?.paths?.[targetPath];
+  if (!methods) {
+    // 끝 슬래시/대소문자 보정 한 번 시도
+    const found = Object.keys(doc?.paths ?? {}).find(
+      (p) => p.toLowerCase() === String(targetPath).toLowerCase(),
+    );
+    if (!found) return { ok: false, error: `해당 path 없음: ${targetPath}` };
+    targetPath = found;
+  }
+  const pathItem = doc.paths[targetPath];
+  const wanted = method ? [method.toLowerCase()] : METHODS;
+  const operations = {};
+  for (const m of wanted) {
+    const op = pathItem[m];
+    if (!op) continue;
+    operations[m.toUpperCase()] = {
+      summary: op.summary,
+      operationId: op.operationId,
+      tags: op.tags,
+      parameters: deref(doc, op.parameters),
+      requestBody: deref(doc, op.requestBody),
+      responses: deref(doc, op.responses),
+    };
+  }
+  if (Object.keys(operations).length === 0) {
+    return { ok: false, error: `${targetPath} 에 ${method ?? ''} 메서드 없음` };
+  }
+  return { ok: true, path: targetPath, operations };
+}

package/src/openapi/summary.js

@@ -14,8 +14,8 @@
  *     ...
  */
 const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
-const MAX_ENDPOINTS = 200;
-const MAX_BYTES = 8 * 1024;
+const MAX_PATHS = 400;
+const MAX_BYTES = 16 * 1024;
 
 export function summarizeOpenApi(doc) {
   if (!doc || typeof doc !== 'object') return null;
@@ -30,46 +30,42 @@ export function summarizeOpenApi(doc) {
     lines.push(`base: ${servers.slice(0, 3).join(', ')}`);
   }
 
-  const endpoints = [];
+  // path 하나당 한 줄로 메서드를 합친다 (줄 수 절반 + 모델이 path 단위로 보기 쉬움).
+  const byPath = [];
   for (const [pathStr, methods] of Object.entries(doc.paths ?? {})) {
     if (!methods || typeof methods !== 'object') continue;
-    for (const m of METHODS) {
-      const op = methods[m];
-      if (!op || typeof op !== 'object') continue;
-      const desc = op.summary || op.operationId || op.description || '';
-      endpoints.push({
-        method: m.toUpperCase(),
-        path: pathStr,
-        desc: desc.split('\n')[0].slice(0, 90),
-      });
-    }
+    const verbs = METHODS.filter((m) => methods[m] && typeof methods[m] === 'object').map((m) =>
+      m.toUpperCase(),
+    );
+    if (verbs.length === 0) continue;
+    byPath.push({ path: pathStr, verbs });
   }
+  byPath.sort((a, b) => a.path.localeCompare(b.path));
 
-  // 너무 많으면 자른다 — 모델이 알아야 하는 건 "어떤 종류의 엔드포인트가 있다" 정도면 충분.
-  const total = endpoints.length;
-  const shown = endpoints.slice(0, MAX_ENDPOINTS);
+  const total = byPath.length;
+  const shown = byPath.slice(0, MAX_PATHS);
 
-  lines.push(`endpoints: (${shown.length}/${total})`);
+  lines.push(`paths: (${shown.length}/${total})`);
   for (const e of shown) {
-    lines.push(`  ${e.method.padEnd(6)} ${e.path}${e.desc ? '  -- ' + e.desc : ''}`);
+    lines.push(`  ${e.verbs.join(',').padEnd(20)} ${e.path}`);
   }
   if (shown.length < total) {
-    lines.push(`  ... and ${total - shown.length} more`);
+    lines.push(`  ... and ${total - shown.length} more (search_openapi 로 검색하세요)`);
   }
 
   let result = lines.join('\n');
+  // 바이트 초과 시 뒤에서부터 잘라낸다 (search_openapi 가 있으니 전부 못 담아도 안전).
   if (Buffer.byteLength(result, 'utf8') > MAX_BYTES) {
-    // 안전 장치 — desc 다 자르고 다시.
-    const compact = [
-      lines[0],
-      servers.length ? lines[1] : null,
-      `endpoints: (${shown.length}/${total})`,
-      ...shown.map((e) => `  ${e.method.padEnd(6)} ${e.path}`),
-      shown.length < total ? `  ... and ${total - shown.length} more` : null,
-    ]
-      .filter(Boolean)
-      .join('\n');
-    result = compact;
+    const header = [lines[0], servers.length ? lines[1] : null].filter(Boolean);
+    const out = [...header, `paths: (truncated/${total}) — 전체는 search_openapi 로 검색`];
+    let bytes = Buffer.byteLength(out.join('\n'), 'utf8');
+    for (const e of shown) {
+      const line = `  ${e.verbs.join(',').padEnd(20)} ${e.path}`;
+      bytes += Buffer.byteLength(line + '\n', 'utf8');
+      if (bytes > MAX_BYTES) break;
+      out.push(line);
+    }
+    result = out.join('\n');
   }
   return result;
 }

package/src/ui/ChatApp.js

@@ -731,6 +731,7 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       const tools = buildTools({
         projectRoot,
         effective: cfg.effective,
+        openapiSource: cfg.effective.api?.openapi ?? null,
         onEvent: onToolEvent,
       });