byuckchon-frontend-cli 1.9.1 → 1.9.2

package/README.md

@@ -193,6 +193,10 @@ FE 전반의 규칙(폴더 구조, 네이밍, 스웨거 → 코드 변환 규칙
 
 - **OpenAPI**: chat 시작 시 자동 fetch + 1시간 디스크 캐시 → 엔드포인트 요약을 시스템 프롬프트에 박음.
   - 헤더에 `openapi` 줄로 표시. 캐시 hit 면 `(cached)`, fresh fetch 면 `(live)`.
+  - **세션 중 서버가 스펙을 바꿔도 자동 대응 (v1.10+)**: `search_openapi` / `get_openapi_endpoint` 가
+    캐시에서 엔드포인트를 못 찾으면 **딱 한 번 최신본을 다시 받아 재검색**합니다 (`🔄 OpenAPI 스펙 새로고침`).
+    남용 방지를 위해 세션당 횟수·간격이 제한됩니다. "방금 스웨거 업데이트했어, 다시 읽어줘" 라고 하면
+    즉시 강제 새로고침(`refresh_openapi`)합니다.
 - **코드 인덱스**: chat 시작 시 인덱스 파일이 없으면 **백그라운드에서 자동 빌드**.
   - 빌드 중에는 화면에 `📚 인덱싱 중 ...` 진행 표시. 끝나면 `✓` 메시지 한 줄.
   - OpenAI 키가 없으면 빌드를 건너뛰고 도움 메시지를 띄움 (Anthropic 은 임베딩 API 미제공).

package/bin/index.js

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

package/package.json

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

package/src/ai/tools.js

@@ -44,6 +44,39 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
     return _openapiDocPromise;
   }
 
+  // ── live refetch (서버가 세션 도중 스펙을 바꾼 경우 대비) ──
+  // 남용 방지: 세션당 최대 횟수 + 최소 간격 throttle.
+  const REFRESH_MAX = 6;
+  const REFRESH_MIN_INTERVAL_MS = 10_000;
+  let _refreshCount = 0;
+  let _lastRefreshAt = 0;
+
+  /**
+   * 캐시를 무시하고 OpenAPI 스펙을 다시 fetch 한다.
+   * @returns {Promise<{ doc: object|null, refreshed: boolean, reason?: string }>}
+   */
+  async function refreshOpenApiDoc() {
+    if (!openapiSource) return { doc: null, refreshed: false, reason: 'no-source' };
+
+    const now = Date.now();
+    if (_refreshCount >= REFRESH_MAX) {
+      return { doc: await loadOpenApiDoc(), refreshed: false, reason: 'limit' };
+    }
+    if (now - _lastRefreshAt < REFRESH_MIN_INTERVAL_MS) {
+      return { doc: await loadOpenApiDoc(), refreshed: false, reason: 'throttled' };
+    }
+
+    _refreshCount += 1;
+    _lastRefreshAt = now;
+    _openapiDocPromise = getCachedOpenApi(openapiSource, { force: true })
+      .then((res) => res.doc ?? null)
+      .catch(() => null);
+
+    const doc = await _openapiDocPromise;
+    onEvent({ kind: 'openapi_refreshed', ok: !!doc });
+    return { doc, refreshed: true };
+  }
+
   function safePath(p) {
     if (!p || typeof p !== 'string') {
       throw new Error('path 가 비어있습니다');
@@ -188,7 +221,11 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
   // ─────────── OpenAPI 툴 ───────────
 
   async function searchOpenApi({ query, limit = 40 }) {
-    const doc = await loadOpenApiDoc();
+    let doc = await loadOpenApiDoc();
+    if (!doc) {
+      // 첫 로드 실패면 한 번 live refetch 시도.
+      ({ doc } = await refreshOpenApiDoc());
+    }
     if (!doc) {
       return {
         ok: false,
@@ -197,11 +234,25 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
           '(NestJS 는 보통 /api/docs 가 아니라 /api/docs-json).',
       };
     }
-    const hits = searchEndpoints(doc, query, { limit });
+
+    let hits = searchEndpoints(doc, query, { limit });
+    let refreshed = false;
+
+    // 캐시된 스펙에서 못 찾으면 → 서버에서 방금 추가됐을 수 있으니 딱 한 번 live refetch 후 재검색.
+    if (hits.length === 0) {
+      const r = await refreshOpenApiDoc();
+      if (r.refreshed && r.doc) {
+        refreshed = true;
+        doc = r.doc;
+        hits = searchEndpoints(doc, query, { limit });
+      }
+    }
+
     return {
       ok: true,
       query,
       count: hits.length,
+      refreshed,
       endpoints: hits.map((e) => ({
         method: e.method,
         path: e.path,
@@ -210,17 +261,63 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
       })),
       hint:
         hits.length === 0
-          ? '매치 없음. 다른 키워드로 재시도하거나, query 를 비워 전체 목록을 받아 path 를 직접 고르세요.'
-          : '상세 스키마가 필요하면 get_openapi_endpoint(path, method) 를 호출하세요.',
+          ? (refreshed
+              ? '최신 스펙을 다시 받아왔는데도 매치가 없습니다. 다른 키워드로 재시도하거나 query 를 비워 전체 목록을 확인하세요.'
+              : '매치 없음. 다른 키워드로 재시도하거나, query 를 비워 전체 목록을 받아 path 를 직접 고르세요.')
+          : (refreshed
+              ? '캐시엔 없던 항목을 최신 스펙에서 찾았습니다. 상세는 get_openapi_endpoint(path, method).'
+              : '상세 스키마가 필요하면 get_openapi_endpoint(path, method) 를 호출하세요.'),
     };
   }
 
   async function getOpenApiEndpoint({ path: epPath, method }) {
-    const doc = await loadOpenApiDoc();
+    let doc = await loadOpenApiDoc();
+    if (!doc) {
+      ({ doc } = await refreshOpenApiDoc());
+    }
     if (!doc) {
       return { ok: false, error: 'OpenAPI 스펙을 불러올 수 없습니다.' };
     }
-    return getEndpoint(doc, epPath, method);
+
+    let result = getEndpoint(doc, epPath, method);
+
+    // 못 찾으면 → 최신 스펙으로 한 번 더.
+    if (!result.ok) {
+      const r = await refreshOpenApiDoc();
+      if (r.refreshed && r.doc) {
+        const retry = getEndpoint(r.doc, epPath, method);
+        if (retry.ok) result = { ...retry, refreshed: true };
+        else result = { ...retry, refreshed: true };
+      }
+    }
+    return result;
+  }
+
+  async function refreshOpenApi() {
+    if (!openapiSource) {
+      return { ok: false, error: 'bc.config.json 에 api.openapi 가 설정되어 있지 않습니다.' };
+    }
+    const r = await refreshOpenApiDoc();
+    if (!r.doc) {
+      return {
+        ok: false,
+        refreshed: r.refreshed,
+        error:
+          r.reason === 'throttled'
+            ? '방금 새로고침했습니다. 잠시 후 다시 시도하세요.'
+            : '스펙을 다시 받아오지 못했습니다 (네트워크/URL 확인).',
+      };
+    }
+    const count = (r.doc.paths ? Object.keys(r.doc.paths).length : 0);
+    return {
+      ok: true,
+      refreshed: r.refreshed,
+      reason: r.refreshed ? undefined : r.reason,
+      paths: count,
+      message: r.refreshed
+        ? `최신 OpenAPI 스펙을 다시 받아왔습니다 (path ${count}개).`
+        : '최근에 이미 새로고침되어 캐시를 재사용했습니다.',
+    };
   }
 
   // ─────────── Figma 툴 ───────────
@@ -381,6 +478,20 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
       }),
       execute: getOpenApiEndpoint,
     }),
+    refresh_openapi: tool({
+      description:
+        '연결된 OpenAPI(Swagger) 스펙을 캐시 무시하고 서버에서 다시 받아온다. ' +
+        '사용자가 "방금 스웨거(백엔드 API) 를 업데이트했다 / 다시 읽어라" 라고 하거나, ' +
+        'search_openapi 가 분명히 있어야 할 엔드포인트를 못 찾을 때 호출. ' +
+        '(search_openapi / get_openapi_endpoint 는 못 찾으면 자동으로 한 번 새로고침하므로, ' +
+        '명시적 요청이 있을 때만 직접 부르면 된다.)',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      }),
+      execute: refreshOpenApi,
+    }),
     write_file: tool({
       description:
         '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',

package/src/commands/chat.js

@@ -121,6 +121,9 @@ export async function chatCommand(opts = {}) {
           '가져와서 zod/타입/요청 함수를 만든다. ' +
           '예: 사용자가 "inquiries" 라고 하면 search_openapi("inquiries") 로 ' +
           '`/api/admin/inquiries` 같은 실제 경로를 찾아낸다. ' +
+          '스펙은 캐시(최대 1시간)라 서버가 방금 바꿨으면 오래됐을 수 있다 — ' +
+          'search_openapi/get_openapi_endpoint 는 못 찾으면 자동으로 한 번 최신본을 다시 받아온다. ' +
+          '사용자가 "방금 스웨거 업데이트했어/다시 읽어" 라고 하면 `refresh_openapi()` 를 먼저 호출한다. ' +
           '이미 `*.gen.ts` 가 있으면 그걸 import 해서 쓰는 것도 좋다.';
       }
     } catch {
@@ -264,6 +267,12 @@ async function runOnce({ cfg, resolved, system, prompt }) {
     effective: cfg.effective,
     openapiSource: cfg.effective.api?.openapi ?? null,
     onEvent: (ev) => {
+      if (ev.kind === 'openapi_refreshed') {
+        console.log(
+          chalk.dim(ev.ok ? '  🔄 OpenAPI 스펙 새로고침' : '  ⚠️  OpenAPI 새로고침 실패'),
+        );
+        return;
+      }
       const label =
         ev.kind === 'write_created'
           ? '🆕'
@@ -489,6 +498,12 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       effective: cfg.effective,
       openapiSource: cfg.effective.api?.openapi ?? null,
       onEvent: (ev) => {
+        if (ev.kind === 'openapi_refreshed') {
+          console.log(
+            chalk.dim(ev.ok ? '\n  🔄 OpenAPI 스펙 새로고침' : '\n  ⚠️  OpenAPI 새로고침 실패'),
+          );
+          return;
+        }
         const label =
           ev.kind === 'write_created'
             ? '🆕 생성'

package/src/openapi/cache.js

@@ -23,8 +23,13 @@ function keyFor(input) {
  *
  * - 네트워크 실패 시: 만료된 캐시라도 있으면 그걸로 폴백 (offline-friendly).
  * - 캐시는 .bc/cache/openapi-<hash>.json 에 저장.
+ *
+ * @param {string} input  OpenAPI URL 또는 파일 경로
+ * @param {object} [opts]
+ * @param {boolean} [opts.force]  true 면 TTL 무시하고 무조건 live refetch (캐시 갱신).
+ *                                서버가 세션 도중 스펙을 바꿨을 때 사용.
  */
-export async function getCachedOpenApi(input) {
+export async function getCachedOpenApi(input, { force = false } = {}) {
   const dir = await getCacheDir();
   const file = path.join(dir, `openapi-${keyFor(input)}.json`);
 
@@ -39,7 +44,7 @@ export async function getCachedOpenApi(input) {
     /* miss */
   }
 
-  if (cachedFresh && cached) {
+  if (!force && cachedFresh && cached) {
     return { doc: cached, cached: true, source: input };
   }
 

package/src/ui/ChatApp.js

@@ -871,6 +871,18 @@ export function ChatApp({
 
       // 툴 실행 이벤트는 채팅에 시스템 메시지로 표시 (사용자가 무엇이 일어났는지 보게).
       const onToolEvent = (ev) => {
+        if (ev.kind === 'openapi_refreshed') {
+          setMessages((m) => [
+            ...m,
+            {
+              role: 'system-info',
+              text: ev.ok
+                ? '🔄 OpenAPI 스펙 새로고침 (서버에서 최신본 다시 받음)'
+                : '⚠️  OpenAPI 새로고침 실패 (네트워크/URL 확인)',
+            },
+          ]);
+          return;
+        }
         const labels = {
           write_created: '🆕 생성',
           write_overwritten: '✏️  덮어씀',