byuckchon-frontend-cli 1.7.0 → 1.9.1

package/README.md

@@ -156,6 +156,36 @@ bc › Auto layout 이 row 였고 padding 12/16 이었어요. MemberCard 만들
 > Figma 응답은 자동으로 압축됩니다 (자식 60개, 깊이 8 까지). 너무 큰 프레임은 더 작은
 > 자식 frame URL 을 줘서 분할 정복하세요.
 
+### 팀 컨벤션 문서(.md) 자동 주입 (v1.8+)
+
+FE 전반의 규칙(폴더 구조, 네이밍, 스웨거 → 코드 변환 규칙 등)을 `.md` 로 적어두면
+**매 chat 세션에 시스템 프롬프트로 자동 주입**됩니다. AI 는 기존 코드 패턴보다 이 문서를 우선합니다.
+
+**파일명은 고정이 아닙니다.** 아무 경로나 `bc.config.json` 의 `docs` 에 적으면 됩니다.
+적지 않으면 관례 파일명(`bc.md`, `.bc/conventions.md`, `AGENTS.md`, `FRONTEND.md`, `docs/frontend.md`)을 자동 탐지합니다.
+
+```json
+{
+  "docs": ["docs/fe-conventions.md", "docs/api-guide.md"]
+}
+```
+
+- 문서당 최대 24KB, 전체 48KB 까지 (토큰 폭발 방지). 헤더에 `docs` 줄로 로드된 파일이 표시됩니다.
+- (고급) 항목을 `{ "path": "...", "when": { "framework": "next" } }` 형태로 적으면 프레임워크별 조건부 주입도 가능합니다.
+
+#### API 코드 컨벤션 .md 자동 포함
+
+`bc init` / `bc adopt` 를 실행하면 **API 코드 생성 가이드(`api-codegen.md`)가 프레임워크에 맞는 위치에 자동으로 깔립니다.**
+
+| 프레임워크 | 위치 |
+| --- | --- |
+| React (Vite/CRA 등) | `src/api/api-codegen.md` |
+| Next.js | `lib/api/api-codegen.md` |
+
+- 이 파일은 `bc.config.json` 의 `docs` 에 자동 등록되어 **chat 시작 시 주입**됩니다.
+- 하나의 .md 로 React/Next 를 모두 다루며(차이는 위치뿐), 팀 규칙에 맞게 직접 다듬어 쓰면 됩니다.
+- 이미 파일이 있으면 덮어쓰지 않습니다.
+
 ### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
 
 `bc.config.json` 의 `api.openapi` 와 코드 인덱스는 **chat 시작할 때 알아서 준비됩니다.**
@@ -254,6 +284,8 @@ TTY 안에서 자동으로 ink 모드로 뜨고, 파이프/CI 같은 비-TTY 환
 | ------------------- | ------------------------------------------ |
 | `/help`             | 도움말                                     |
 | `/clear`            | 대화 컨텍스트 초기화                        |
+| `/history`          | 이전 대화 선택 후 해당 컨텍스트 이어가기     |
+| `/retry`            | 마지막 사용자 요청 다시 실행                |
 | `/model [id]`       | 세션 모델 변경 (인자 없으면 목록)           |
 | `/cost`             | 누적 토큰/비용                              |
 | `/image <path>`     | 다음 메시지에 이미지 첨부 (Vision 모델 권장) |
@@ -264,6 +296,10 @@ TTY 안에서 자동으로 ink 모드로 뜨고, 파이프/CI 같은 비-TTY 환
 | `/rag on\|off`      | RAG 컨텍스트 주입 즉석 토글                 |
 | `/exit`             | 종료 (`Ctrl+C` 도 가능)                     |
 
+Ink 모드에서 `/history`를 실행하면 `↑↓`로 세션을 선택하고 `Enter`로 불러올 수 있습니다.
+선택한 세션에서 `d`를 누른 뒤 `y`로 확인하면 해당 기록을 삭제합니다. 메시지를 한 번도
+보내지 않고 종료한 빈 세션은 저장되거나 목록에 표시되지 않습니다.
+
 이미지 첨부는 png / jpg / jpeg / gif / webp 만 지원하며,
 Claude / GPT 비전 모델에 멀티파트 메시지로 전달됩니다.
 

package/bin/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.7.0",
+  "version": "1.9.1",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {
@@ -34,6 +34,7 @@
   "files": [
     "bin",
     "src",
+    "templates",
     "README.md"
   ],
   "keywords": [

package/src/commands/adopt.js

@@ -7,6 +7,10 @@ import inquirer from 'inquirer';
 import { detectProjectContext, summarizeContext } from '../context/detect.js';
 import { CONFIG_PATHS } from '../config/index.js';
 import { modelChoices, DEFAULT_MODEL_ID } from '../ai/models.js';
+import {
+  apiRootForFramework,
+  scaffoldApiConventionDoc,
+} from '../generators/apiConventionDoc.js';
 
 /**
  * `bc adopt`
@@ -119,6 +123,9 @@ export async function adoptCommand(opts = {}) {
       exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**', '.next/**'],
       maxFiles: 20,
     },
+    docs: existing?.docs ?? [
+      path.posix.join(apiRootForFramework(ctx.framework), 'api-codegen.md'),
+    ],
     framework: ctx.framework,
     detected: {
       language: ctx.language,
@@ -136,7 +143,23 @@ export async function adoptCommand(opts = {}) {
   await fs.writeFile(targetFile, JSON.stringify(next, null, 2) + '\n', 'utf8');
 
   console.log(chalk.green(`\n  ✓ ${CONFIG_PATHS.projectFileName} 작성 완료.`));
-  console.log(chalk.dim(`    ${targetFile}\n`));
+  console.log(chalk.dim(`    ${targetFile}`));
+
+  // API 코드 컨벤션 .md 를 API 루트(src/api | lib/api)에 깐다 (이미 있으면 유지).
+  try {
+    const { relPath, written } = await scaffoldApiConventionDoc({
+      projectRoot: cwd,
+      framework: ctx.framework,
+    });
+    if (written) {
+      console.log(chalk.green(`  ✓ API 코드 컨벤션 문서 생성: ${relPath}`));
+    } else {
+      console.log(chalk.dim(`  API 코드 컨벤션 문서 유지: ${relPath} (이미 존재)`));
+    }
+  } catch {
+    /* 문서 스캐폴드 실패는 치명적이지 않음 */
+  }
+  console.log();
   console.log(chalk.dim('  다음:'));
   if (!process.env.ANTHROPIC_API_KEY) {
     console.log(chalk.dim('    bc config set-key anthropic    # API 키 등록'));

package/src/commands/chat.js

@@ -17,10 +17,12 @@ import { printInlineThumbnail } from '../ai/imagePreview.js';
 import {
   createSession,
   saveSession,
+  deleteSession,
   listSessions,
   loadSession,
   loadLatestSession,
 } from '../history/store.js';
+import { findLastRetryableUser, formatSessionList } from '../history/management.js';
 import { getCachedOpenApi } from '../openapi/cache.js';
 import { summarizeOpenApi } from '../openapi/summary.js';
 
@@ -63,12 +65,37 @@ export async function chatCommand(opts = {}) {
     process.exit(1);
   }
 
-  const baseSystem = buildSystemPrompt({
+  let baseSystem = buildSystemPrompt({
     effective: cfg.effective,
     paths: cfg.paths,
     project: cfg.project,
   });
 
+  // 컨벤션 문서(.md) 자동 주입 — FE 전반 규칙, 스웨거→코드 변환 규칙 등.
+  // bc.config.json 의 docs:[...] 또는 bc.md/AGENTS.md 등 관례 파일을 읽는다.
+  let conventionFiles = [];
+  if (cfg.paths.projectFile) {
+    try {
+      const { loadConventionDocs } = await import('../context/conventions.js');
+      const projectRoot = path.dirname(cfg.paths.projectFile);
+      const conv = await loadConventionDocs({
+        projectRoot,
+        docs: cfg.effective.docs,
+        framework: cfg.project?.framework ?? cfg.project?.detected?.framework,
+      });
+      if (conv.text) {
+        conventionFiles = conv.files;
+        baseSystem +=
+          '\n\n---\n## 팀 컨벤션 문서 (반드시 우선 준수)\n' +
+          '아래는 이 프로젝트/팀의 프론트엔드 컨벤션이다. 코드 생성·수정 시 여기 규칙을 ' +
+          '기존 코드 패턴보다 우선 적용한다. 충돌하면 이 문서를 따른다.\n\n' +
+          conv.text;
+      }
+    } catch {
+      /* 문서 로딩 실패는 무시 */
+    }
+  }
+
   // OpenAPI 자동 주입 — bc.config.json 의 api.openapi 가 있으면 fetch 후 요약을
   // 시스템 프롬프트에 박는다. 1시간 캐시. 실패해도 chat 은 그대로 동작.
   let openapiInfo = null;
@@ -137,18 +164,16 @@ export async function chatCommand(opts = {}) {
     // 모델은 사용자가 명시했거나 글로벌 설정으로 갱신 가능 — 세션의 model 은 표시용.
     session.model = resolved.meta.id;
   }
-  await saveSession(session); // 빈 파일이라도 디스크에 만들어둠
-
   // ink 는 stdin/stdout 둘 다 TTY 이어야 정상 동작.
   // - --plain 플래그가 명시되거나 비-TTY 면 readline 폴백.
   // - 글로벌 ui.mode 가 "plain" 이면 한글 IME 가 깨지는 케이스를 자동 회피.
   const isTTY = process.stdin.isTTY && process.stdout.isTTY;
   const wantPlain = opts.plain || cfg.global?.ui?.mode === 'plain';
   if (!isTTY || wantPlain) {
-    return runReadlineFallback({ cfg, resolved, system, session, openapiInfo });
+    return runReadlineFallback({ cfg, resolved, system, session, openapiInfo, conventionFiles });
   }
 
-  return runInkApp({ cfg, resolved, system, session, openapiInfo });
+  return runInkApp({ cfg, resolved, system, session, openapiInfo, conventionFiles });
 }
 
 async function printHistoryList() {
@@ -172,18 +197,45 @@ async function printHistoryList() {
 
 /* ───────────────────────── ink 모드 ───────────────────────── */
 
-async function runInkApp({ cfg, resolved, system, session, openapiInfo }) {
+async function runInkApp({ cfg, resolved, system, session, openapiInfo, conventionFiles = [] }) {
   // ink/React 는 무겁고 비-TTY 환경에서 import 만으로도 종종 문제 일으키므로
   // 여기서 늦게 import 한다 (--once / pipe 모드에 영향 없도록).
   const { render } = await import('ink');
   const { ChatApp } = await import('../ui/ChatApp.js');
   const React = (await import('react')).default;
 
-  const initialConfig = { ...cfg, system, openapiInfo };
+  const initialConfig = { ...cfg, system, openapiInfo, conventionFiles };
+
+  let activeSession = session;
 
   const onSessionUpdate = async (messages) => {
-    session.messages = messages;
-    await saveSession(session);
+    const target = activeSession;
+    const hasConversation = messages.some(
+      (message) =>
+        (message.role === 'user' || message.role === 'assistant') &&
+        typeof message.text === 'string' &&
+        message.text.trim(),
+    );
+    if (!hasConversation && !target._persisted) return;
+    target.messages = messages;
+    await saveSession(target);
+  };
+
+  const onSessionSwitch = async (id) => {
+    const loaded = await loadSession(id);
+    loaded.model = resolved.meta.id;
+    activeSession = loaded;
+    return loaded;
+  };
+
+  const onSessionDelete = async (id) => {
+    const deletingActive = activeSession.id === id;
+    const result = await deleteSession(id);
+    if (!deletingActive) return { ...result, replacementSession: null };
+
+    const replacementSession = await createSession({ model: resolved.meta.id });
+    activeSession = replacementSession;
+    return { ...result, replacementSession };
   };
 
   const { waitUntilExit } = render(
@@ -192,6 +244,8 @@ async function runInkApp({ cfg, resolved, system, session, openapiInfo }) {
       initialResolved: resolved,
       session,
       onSessionUpdate,
+      onSessionSwitch,
+      onSessionDelete,
     }),
     { exitOnCtrlC: false },
   );
@@ -247,7 +301,7 @@ async function runOnce({ cfg, resolved, system, prompt }) {
 
 /* ──────────────────── 비-TTY / --plain 폴백 ──────────────────── */
 
-async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo }) {
+async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo, conventionFiles = [] }) {
   const readline = await import('node:readline');
   const meter = new TokenMeter(resolved.meta, cfg.effective.limits);
 
@@ -259,11 +313,16 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       chalk.dim('  openapi: ' + openapiInfo.source + (openapiInfo.cached ? ' (cached)' : ' (live)')),
     );
   }
+  if (conventionFiles.length) {
+    console.log(chalk.dim('  컨벤션 문서: ' + conventionFiles.join(', ')));
+  }
   if (session?.messages?.length) {
     console.log(chalk.dim(`  세션: ${session.id} (${session.messages.length} turns 이어가기)`));
   }
   console.log(
-    chalk.dim('  /image <경로> · /paste(클립보드 이미지) · /clear-attach · /exit\n'),
+    chalk.dim(
+      '  /history · /retry · /image <경로> · /paste · /clear-attach · /exit\n',
+    ),
   );
 
   // 다음 메시지에 함께 보낼 이미지 첨부 목록.
@@ -313,6 +372,21 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
   const history = (session?.messages ?? [])
     .filter((m) => m.role === 'user' || m.role === 'assistant')
     .map((m) => ({ role: m.role, content: m.text ?? '' }));
+  const persistHistory = async () => {
+    if (!session) return;
+    session.messages = history.map((message) => {
+      // 이미지 바이트는 세션 파일에 저장하지 않고 사용자 텍스트만 보존한다.
+      if (Array.isArray(message.content)) {
+        const textPart = message.content.find((part) => part.type === 'text');
+        return {
+          role: message.role,
+          text: textPart?.text ?? '[이미지 첨부]',
+        };
+      }
+      return { role: message.role, text: message.content };
+    });
+    await saveSession(session);
+  };
   const ask = () => rl.prompt();
 
   rl.on('close', () => {
@@ -331,6 +405,29 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       rl.close();
       return;
     }
+    if (line === '/history') {
+      try {
+        const sessions = await listSessions();
+        console.log(chalk.dim('\n' + formatSessionList(sessions)));
+        console.log(chalk.dim('\n  이어가기: bc chat --resume <id>'));
+      } catch (err) {
+        console.log(chalk.red('  대화 목록을 불러올 수 없습니다: ' + err.message));
+      }
+      ask();
+      continue;
+    }
+    let retryContent = null;
+    if (line === '/retry') {
+      const retry = findLastRetryableUser(history);
+      if (!retry) {
+        console.log(chalk.red('  다시 실행할 사용자 요청이 없습니다.'));
+        ask();
+        continue;
+      }
+      retryContent = retry.message.content;
+      history.splice(retry.index);
+      console.log(chalk.dim('  마지막 요청을 다시 실행합니다.'));
+    }
     // 이미지 첨부 관련 슬래시 명령 — plain 모드에서도 지원.
     if (line.startsWith('/image')) {
       await addImage(line.slice('/image'.length).trim());
@@ -360,7 +457,9 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     }
 
     // 일반 메시지 — 첨부가 있으면 멀티모달 content 로 구성.
-    if (pendingAttachments.length) {
+    if (retryContent != null) {
+      history.push({ role: 'user', content: retryContent });
+    } else if (pendingAttachments.length) {
       const parts = [{ type: 'text', text: line }];
       try {
         for (const att of pendingAttachments) {
@@ -375,6 +474,11 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     } else {
       history.push({ role: 'user', content: line });
     }
+    try {
+      await persistHistory();
+    } catch {
+      /* 저장 실패가 AI 요청을 막지는 않게 한다. */
+    }
     rl.pause();
 
     const projectRoot = cfg.paths.projectFile
@@ -429,21 +533,11 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     }
     if (acc) history.push({ role: 'assistant', content: acc });
 
-    // 세션 자동 저장 — readline 모드에서도 끊김 대비.
-    if (session) {
-      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 {
-        /* noop */
-      }
+    // 응답까지 포함한 최신 상태로 다시 저장한다.
+    try {
+      await persistHistory();
+    } catch {
+      /* noop */
     }
 
     rl.resume();

package/src/config/index.js

@@ -65,6 +65,11 @@ const DEFAULT_PROJECT = {
     exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**'],
     maxFiles: 20,
   },
+  /**
+   * FE 전반 컨벤션을 적은 .md 경로들. 매 chat 세션에 시스템 프롬프트로 주입된다.
+   * 비우면 bc.md / .bc/conventions.md / AGENTS.md 등을 자동 탐지.
+   */
+  docs: [],
   /** bc adopt 가 채워준다. systemPrompt 가 읽어 모델에 알린다. */
   framework: null,
   detected: null,
@@ -181,6 +186,7 @@ export async function loadEffectiveConfig(startDir = process.cwd()) {
       design: project.design,
       api: project.api,
       context: project.context,
+      docs: project.docs ?? [],
     },
   };
 }

package/src/context/conventions.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 프로젝트의 "컨벤션 문서(.md)" 를 찾아 읽어서 시스템 프롬프트에 주입할 텍스트로 만든다.
+ *
+ * 우선순위:
+ *   1) bc.config.json 의 `docs: [...]` 에 명시된 항목 (순서대로)
+ *      - 항목은 문자열(경로) 이거나, 조건부 객체일 수 있다:
+ *        "docs/common.md"
+ *        { "path": "docs/api-codegen.md", "when": { "frameworkNot": "next" } }
+ *        { "path": "docs/api-next.md",    "when": { "framework": "next" } }
+ *      - when 의 framework / frameworkNot 는 문자열 또는 문자열 배열.
+ *   2) 명시가 없으면 프로젝트 루트의 관례적 파일명 자동 탐지
+ *      - bc.md, .bc/conventions.md, AGENTS.md, FRONTEND.md, docs/frontend.md
+ *
+ * 토큰 폭발 방지: 문서당 최대 bytes, 전체 합계 최대 bytes 로 컷.
+ */
+const AUTO_NAMES = [
+  'bc.md',
+  '.bc/conventions.md',
+  'AGENTS.md',
+  'FRONTEND.md',
+  'docs/frontend.md',
+  'docs/FRONTEND.md',
+];
+
+const PER_DOC_MAX = 24 * 1024;
+const TOTAL_MAX = 48 * 1024;
+
+async function readIfExists(abs) {
+  try {
+    const stat = await fs.stat(abs);
+    if (!stat.isFile()) return null;
+    let text = await fs.readFile(abs, 'utf8');
+    if (Buffer.byteLength(text, 'utf8') > PER_DOC_MAX) {
+      text = text.slice(0, PER_DOC_MAX) + '\n... (이하 생략 — 문서가 너무 깁니다)';
+    }
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+function asArray(v) {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+/** docs 항목의 when 조건이 현재 framework 에 맞는지. */
+function matchesFramework(when, framework) {
+  if (!when || typeof when !== 'object') return true;
+  const fw = framework || 'unknown';
+
+  const only = asArray(when.framework);
+  if (only.length && !only.includes(fw)) return false;
+
+  const not = asArray(when.frameworkNot);
+  if (not.length && not.includes(fw)) return false;
+
+  return true;
+}
+
+/** docs 항목(문자열 | 객체)을 { path, when } 로 정규화. */
+function normalizeEntry(entry) {
+  if (typeof entry === 'string') return { path: entry, when: null };
+  if (entry && typeof entry === 'object' && typeof entry.path === 'string') {
+    return { path: entry.path, when: entry.when ?? null };
+  }
+  return null;
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot  bc.config.json 이 있는 디렉터리
+ * @param {Array<string|object>} [args.docs]  config 의 docs (문자열 또는 조건부 객체)
+ * @param {string} [args.framework]  detect.js 의 framework (조건부 docs 판별용)
+ * @returns {Promise<{ text: string|null, files: string[] }>}
+ */
+export async function loadConventionDocs({ projectRoot, docs, framework }) {
+  if (!projectRoot) return { text: null, files: [] };
+
+  const explicit = Array.isArray(docs) && docs.length > 0;
+  const rawEntries = explicit ? docs : AUTO_NAMES;
+
+  const entries = rawEntries
+    .map(normalizeEntry)
+    .filter(Boolean)
+    .filter((e) => matchesFramework(e.when, framework));
+
+  const collected = [];
+  const files = [];
+  let total = 0;
+
+  for (const { path: rel } of entries) {
+    const abs = path.resolve(projectRoot, rel);
+    // 루트 밖 경로는 무시 (안전)
+    const within = !path.relative(projectRoot, abs).startsWith('..');
+    if (!within) continue;
+
+    const content = await readIfExists(abs);
+    if (!content) continue;
+
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (total + bytes > TOTAL_MAX) break;
+    total += bytes;
+
+    files.push(rel);
+    collected.push(`### 문서: ${rel}\n${content}`);
+  }
+
+  if (collected.length === 0) return { text: null, files: [] };
+  return { text: collected.join('\n\n'), files };
+}

package/src/generators/apiConventionDoc.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../templates/conventions/api-codegen.md',
+);
+
+/**
+ * 프레임워크에 맞는 API 루트 폴더.
+ * - Next.js → lib/api
+ * - 그 외 React 계열 → src/api
+ */
+export function apiRootForFramework(framework) {
+  return framework === 'next' ? 'lib/api' : 'src/api';
+}
+
+/**
+ * API 코드 컨벤션 .md 를 프로젝트의 API 루트(`src/api` 또는 `lib/api`)에 깐다.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.framework   'react' | 'next' | detect.js 의 framework 값
+ * @param {boolean} [args.force]    이미 있으면 덮어쓸지
+ * @returns {Promise<{ relPath: string, written: boolean }>}
+ */
+export async function scaffoldApiConventionDoc({ projectRoot, framework, force = false }) {
+  const apiRoot = apiRootForFramework(framework);
+  const relPath = path.join(apiRoot, 'api-codegen.md');
+  const absPath = path.join(projectRoot, relPath);
+
+  let exists = false;
+  try {
+    await fs.access(absPath);
+    exists = true;
+  } catch {
+    /* not there */
+  }
+
+  if (exists && !force) {
+    return { relPath, written: false };
+  }
+
+  const template = await fs.readFile(TEMPLATE_PATH, 'utf8');
+  await fs.mkdir(path.dirname(absPath), { recursive: true });
+  await fs.writeFile(absPath, template, 'utf8');
+  return { relPath, written: true };
+}

package/src/generators/createBcConfig.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { apiRootForFramework } from './apiConventionDoc.js';
+
 /**
  * 새 프로젝트 루트에 `bc.config.json` 을 만든다.
  *
@@ -28,6 +30,8 @@ export async function createBcConfig(rootDir, config) {
       exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**'],
       maxFiles: 20,
     },
+    // chat 시작 시 자동 주입되는 팀 컨벤션 문서. API 코드 가이드가 기본 포함.
+    docs: [path.posix.join(apiRootForFramework(config.framework), 'api-codegen.md')],
     framework: config.framework,
     // init 단계에선 사용자가 React/Next 중 골랐고 TS/Tailwind 가 항상 들어가니
     // 감지 결과를 미리 채워둔다 (bc adopt 의 detected 와 같은 모양).

package/src/generators/createProject.js

@@ -8,6 +8,7 @@ import { createBcConfig } from './createBcConfig.js';
 import { createFolders } from './createFolders.js';
 import { createPackageJson } from './createPackageJson.js';
 import { createReadme } from './createReadme.js';
+import { scaffoldApiConventionDoc } from './apiConventionDoc.js';
 
 const exec = promisify(execCallback);
 const BYUCKCHON_PACKAGES = [
@@ -25,6 +26,8 @@ export async function createProject(config) {
   await createPackageJson(rootDir, config);
   await createBaseFiles(rootDir, config);
   await createReadme(rootDir, config);
+  // API 코드 컨벤션 .md 를 프레임워크에 맞는 API 루트(src/api | lib/api)에 깐다.
+  await scaffoldApiConventionDoc({ projectRoot: rootDir, framework: config.framework });
   await createBcConfig(rootDir, config);
 
   // 최신 버전(latest 포함) 의존성을 실제로 설치해 lockfile까지 생성

package/src/history/management.js

@@ -0,0 +1,30 @@
+function messageText(message) {
+  if (typeof message?.text === 'string') return message.text;
+  if (typeof message?.content === 'string') return message.content;
+  if (Array.isArray(message?.content)) {
+    return message.content.find((part) => part.type === 'text')?.text ?? '[이미지 첨부]';
+  }
+  return '';
+}
+
+export function findLastRetryableUser(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message.role === 'user' && messageText(message).trim()) {
+      return { index, message, text: messageText(message) };
+    }
+  }
+  return null;
+}
+
+export function formatSessionList(sessions, { limit = 10 } = {}) {
+  if (!sessions.length) return '저장된 이전 세션이 없습니다.';
+  return sessions
+    .slice(0, limit)
+    .map((session) => {
+      const when = session.updatedAt?.replace('T', ' ').slice(0, 19) ?? '';
+      const preview = session.preview || '(빈 세션)';
+      return `${session.id}  ${when}  ${session.turns} turns\n  ${preview}`;
+    })
+    .join('\n');
+}