byuckchon-frontend-cli 1.6.1 → 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/` 구조 파악
@@ -351,7 +354,8 @@ bc config set-ui ink                        # 풀 TUI 복귀
 - [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`)
 - [x] v1.6.1 — 툴 스키마 `jsonSchema()` 래핑 (`schema is not a function` 수정), plain 모드 이미지 첨부(`/image`·`/paste`) + iTerm2/kitty 인라인 썸네일
-- [ ] v1.7.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
+- [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.1');
+  .version('1.7.0');
 
 program
   .command('init')

package/package.json

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

package/src/ai/tools.js

@@ -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 }) {
@@ -295,6 +347,40 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
       }),
       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 순서) 을 따른다.',

package/src/commands/chat.js

@@ -86,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/네트워크 실패 — 무시하고 계속. */
@@ -204,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'
@@ -378,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'

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