byuckchon-frontend-cli 1.6.0 → 1.6.1

package/README.md

@@ -264,12 +264,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,6 +350,7 @@ 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`)
+- [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 미리보기
 - [ ] 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.6.1');
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "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 {
@@ -260,31 +260,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 +292,13 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['query'],
         additionalProperties: false,
-      },
+      }),
       execute: searchCode,
     }),
     write_file: tool({
       description:
         '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           path: { type: 'string' },
@@ -306,13 +306,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 +321,7 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['path', 'old_string', 'new_string'],
         additionalProperties: false,
-      },
+      }),
       execute: editFile,
     }),
     fetch_figma: tool({
@@ -330,7 +330,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 +338,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 +355,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,
@@ -254,7 +257,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 +326,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
@@ -340,7 +425,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 {