byuckchon-frontend-cli 1.9.3 → 1.9.5

package/README.md

@@ -104,8 +104,8 @@ bc init
 # 1) Figma → Settings → Personal access tokens → "Generate new token"
 #    Read 권한만 있으면 충분 (file 읽기 / image export 둘 다 read 로 됨)
 
-# 2) 토큰을 .env 에 박기 (gitignore 됨)
-echo "FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxx" >> .env
+# 2) bc init이 만든 .env의 FIGMA_TOKEN 값 채우기 (gitignore 됨)
+FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxx
 
 # 3) bc.config.json 의 design.figma 에 파일/노드 URL 박기 (bc adopt 시점에 입력하거나 직접 편집)
 ```
@@ -250,8 +250,9 @@ bc adopt
 ```
 
 `package.json` 과 디렉터리를 스캔해서 **프레임워크/언어/스타일/라우팅/패키지 매니저** 를 자동 감지하고,
-Figma·OpenAPI URL 만 추가로 묻고 `bc.config.json` 만 떨궈줍니다.
-**소스 코드는 절대 건드리지 않습니다.**
+Figma·OpenAPI URL 만 추가로 묻고 `bc.config.json` 을 생성합니다.
+필수 의존성(`@tanstack/react-query`, `zod`, React 계열의 `axios`)이 없으면 감지한 패키지 매니저로
+자동 설치하며, 기존 소스 코드는 건드리지 않습니다.
 
 지원 감지: Next.js · Expo · Electron · Vite+React · Remix · CRA · 일반 React.
 
@@ -261,7 +262,7 @@ Figma·OpenAPI URL 만 추가로 묻고 `bc.config.json` 만 떨궈줍니다.
 bc                                         # 인자 없이도 chat 진입 (제일 짧은 단축키)
 bc start                                   # chat 의 alias
 bc chat                                    # ink 풀 TUI (기본)
-bc chat --model claude-haiku-4             # 이번 세션만 모델 지정
+bc chat --model claude-fable-5             # 이번 세션만 모델 지정
 bc chat --plain                            # 단순 readline 모드
 bc chat --once "useEffect 의존성 배열 누락된 거 어떻게 찾아?"   # 1회성 호출 (CI/스크립트)
 bc chat -c                                 # 가장 최근 세션 이어가기
@@ -291,6 +292,8 @@ TTY 안에서 자동으로 ink 모드로 뜨고, 파이프/CI 같은 비-TTY 환
 | `/history`          | 이전 대화 선택 후 해당 컨텍스트 이어가기     |
 | `/retry`            | 마지막 사용자 요청 다시 실행                |
 | `/model [id]`       | 세션 모델 변경 (인자 없으면 목록)           |
+| `/figma-link <url\|off>` | 프로젝트 Figma 링크 변경 또는 해제       |
+| `/openapi-link <url\|off>` | 프로젝트 OpenAPI 링크 변경 또는 해제    |
 | `/cost`             | 누적 토큰/비용                              |
 | `/image <path>`     | 다음 메시지에 이미지 첨부 (Vision 모델 권장) |
 | `/paste`            | 클립보드 이미지 첨부 (macOS, `pngpaste` 필요) |
@@ -346,7 +349,7 @@ bc config set-ui ink
 ```bash
 bc config show                              # 현재 적용 중인 설정 확인
 bc config set-model                         # 대화형 모델 선택
-bc config set-model claude-sonnet-4-5       # 직접 지정
+bc config set-model claude-sonnet-5         # 직접 지정
 bc config set-key anthropic                 # 키 안전 입력 (가려짐)
 bc config set-key anthropic sk-ant-...      # 직접 지정
 bc config set-gateway https://ai.example.com  # 사내 게이트웨이 모드
@@ -369,9 +372,10 @@ bc config set-ui ink                        # 풀 TUI 복귀
 
 | id                  | provider  | 추천 용도                          |
 | ------------------- | --------- | ---------------------------------- |
-| `claude-sonnet-4-5` | anthropic | 기본 — 코드 Q&A, 리팩터, 컴포넌트   |
-| `claude-haiku-4`    | anthropic | 짧은 작업, 커밋 메시지 (저렴)       |
-| `claude-opus-4-5`   | anthropic | 큰 리팩터, 아키텍처 설계 (고가)     |
+| `claude-sonnet-5`   | anthropic | 기본 — 코드 Q&A, 리팩터, 컴포넌트   |
+| `claude-sonnet-4-6` | anthropic | 안정 — 이전 세대 밸런스             |
+| `claude-opus-4-8`   | anthropic | 큰 리팩터, 아키텍처 설계 (고가)     |
+| `claude-fable-5`    | anthropic | 짧은 작업, 커밋 메시지 (저렴·빠름)  |
 | `gpt-5`             | openai    | 일반 코드                          |
 | `gpt-5-mini`        | openai    | 저렴한 OpenAI                      |
 

package/bin/index.js

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 
 import { initCommand } from '../src/commands/init.js';
+import { addCommand } from '../src/commands/add.js';
 import { chatCommand } from '../src/commands/chat.js';
 import { adoptCommand } from '../src/commands/adopt.js';
 import {
@@ -32,11 +33,18 @@ program
 
 program
   .command('init')
-  .description('새 프론트엔드 프로젝트 생성 (React/Next.js)')
+  .description('새 프론트엔드 프로젝트 생성 (단일 React/Next 또는 pnpm 모노레포)')
   .action(async () => {
     await initCommand();
   });
 
+program
+  .command('add')
+  .description('기존 pnpm 모노레포에 React/Next 앱 추가 (apps/ 아래)')
+  .action(async () => {
+    await addCommand();
+  });
+
 program
   .command('adopt')
   .description('기존 프로젝트에 bc 설정만 추가 (Expo/Electron/Next/Vite/CRA 자동 감지)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {
@@ -10,6 +10,12 @@
     "byuckchon-frontend-cli": "./bin/index.js",
     "bc": "./bin/index.js"
   },
+  "scripts": {
+    "start": "node bin/index.js",
+    "chat": "node bin/index.js chat",
+    "init": "node bin/index.js init",
+    "config": "node bin/index.js config show"
+  },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.85",
     "@ai-sdk/openai": "^3.0.73",
@@ -59,11 +65,5 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/RevolutionaryWarrior/byuckchon-frontend-cli.git"
-  },
-  "scripts": {
-    "start": "node bin/index.js",
-    "chat": "node bin/index.js chat",
-    "init": "node bin/index.js init",
-    "config": "node bin/index.js config show"
   }
-}
+}

package/src/ai/models.js

@@ -9,32 +9,41 @@
  */
 export const MODEL_CATALOG = [
   {
-    id: 'claude-sonnet-4-5',
-    label: 'Claude Sonnet 4.5  (권장 · 코드 품질·속도 밸런스)',
+    id: 'claude-sonnet-5',
+    label: 'Claude Sonnet 5  (권장 · 코드 품질·속도 밸런스)',
     provider: 'anthropic',
-    apiModel: 'claude-sonnet-4-5',
+    apiModel: 'claude-sonnet-5',
     contextWindow: 200_000,
     pricing: { input: 3, output: 15, cachedInput: 0.3 },
     tier: 'balanced',
   },
   {
-    id: 'claude-haiku-4',
-    label: 'Claude Haiku 4  (저렴 · 짧은 작업·커밋 메시지)',
+    id: 'claude-sonnet-4-6',
+    label: 'Claude Sonnet 4.6  (안정 · 이전 세대 밸런스)',
     provider: 'anthropic',
-    apiModel: 'claude-haiku-4',
+    apiModel: 'claude-sonnet-4-6',
     contextWindow: 200_000,
-    pricing: { input: 0.8, output: 4, cachedInput: 0.08 },
-    tier: 'fast',
+    pricing: { input: 3, output: 15, cachedInput: 0.3 },
+    tier: 'balanced',
   },
   {
-    id: 'claude-opus-4-5',
-    label: 'Claude Opus 4.5  (고성능 · 큰 리팩터·아키텍처)',
+    id: 'claude-opus-4-8',
+    label: 'Claude Opus 4.8  (고성능 · 큰 리팩터·아키텍처)',
     provider: 'anthropic',
-    apiModel: 'claude-opus-4-5',
+    apiModel: 'claude-opus-4-8',
     contextWindow: 200_000,
     pricing: { input: 15, output: 75, cachedInput: 1.5 },
     tier: 'powerful',
   },
+  {
+    id: 'claude-fable-5',
+    label: 'Claude Fable 5  (저렴·빠름 · 짧은 작업·커밋 메시지)',
+    provider: 'anthropic',
+    apiModel: 'claude-fable-5',
+    contextWindow: 200_000,
+    pricing: { input: 1, output: 5, cachedInput: 0.1 },
+    tier: 'fast',
+  },
   {
     id: 'gpt-5',
     label: 'GPT-5  (OpenAI · 일반 코드)',
@@ -55,7 +64,7 @@ export const MODEL_CATALOG = [
   },
 ];
 
-export const DEFAULT_MODEL_ID = 'claude-sonnet-4-5';
+export const DEFAULT_MODEL_ID = 'claude-sonnet-5';
 
 export function findModel(id) {
   return MODEL_CATALOG.find((m) => m.id === id);

package/src/commands/add.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import chalk from 'chalk';
+
+import { askAddQuestions } from '../prompts/initPrompts.js';
+import { createApp } from '../generators/createApp.js';
+import { installMonorepoDeps } from '../generators/install.js';
+import {
+  detectMonorepoRoot,
+  detectScope,
+  appExists,
+} from '../context/monorepo.js';
+
+/**
+ * `bc add`
+ *
+ * 기존 pnpm 모노레포에 React/Next 앱을 하나 추가한다.
+ * (현재 위치에서 위로 올라가며 pnpm-workspace.yaml 을 찾는다.)
+ */
+export async function addCommand() {
+  console.log(chalk.bold.cyan('\n  bc add — 모노레포에 앱 추가\n'));
+
+  const root = await detectMonorepoRoot(process.cwd());
+  if (!root) {
+    console.log(chalk.yellow('  ⚠ pnpm 모노레포를 찾지 못했습니다.'));
+    console.log(
+      chalk.dim(
+        '    모노레포 루트(또는 그 하위)에서 실행하세요. 새로 만들려면 `bc init` → 모노레포.\n',
+      ),
+    );
+    process.exit(1);
+  }
+
+  const scope = await detectScope(root);
+  console.log(chalk.dim(`  모노레포: ${root}`));
+  console.log(chalk.dim(`  scope:    @${scope}\n`));
+
+  const answers = await askAddQuestions({ scope });
+
+  if (await appExists(root, answers.appName)) {
+    console.log(
+      chalk.red(`\n  오류: apps/${answers.appName} 가 이미 존재합니다.\n`),
+    );
+    process.exit(1);
+  }
+
+  const config = { ...answers, projectName: answers.appName, typescript: true };
+  const appDir = path.join(root, 'apps', answers.appName);
+  const appPkgName = `@${scope}/${answers.appName}`;
+
+  console.log(
+    chalk.dim(`  ${answers.framework} 앱을 apps/${answers.appName} 에 생성하는 중...\n`),
+  );
+
+  await createApp({ appDir, config, scope });
+  await addRootDevScript(root, answers.appName, appPkgName);
+  await installMonorepoDeps({ root, appPkgName });
+
+  console.log(chalk.bold.green(`\n  ✓ ${appPkgName} 앱을 추가했습니다!\n`));
+  console.log(chalk.yellow('  실행:\n'));
+  console.log(chalk.white(`    pnpm --filter ${appPkgName} dev`));
+  console.log(chalk.white(`    # 또는  pnpm ${answers.appName}\n`));
+}
+
+/**
+ * 루트 package.json 에 `"<app>": "pnpm --filter <pkg> dev"` 단축 스크립트를 추가.
+ */
+async function addRootDevScript(root, appName, appPkgName) {
+  const pkgPath = path.join(root, 'package.json');
+  let pkg;
+  try {
+    pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  } catch {
+    return;
+  }
+  pkg.scripts = pkg.scripts ?? {};
+  if (!pkg.scripts[appName]) {
+    pkg.scripts[appName] = `pnpm --filter ${appPkgName} dev`;
+    await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  }
+}

package/src/commands/adopt.js

@@ -11,12 +11,13 @@ import {
   apiRootForFramework,
   scaffoldApiConventionDoc,
 } from '../generators/apiConventionDoc.js';
+import { ensureRequiredDependencies } from '../utils/ensureRequiredDependencies.js';
 
 /**
  * `bc adopt`
  *
- * 기존 프로젝트(현재 디렉터리)에 bc.config.json 만 살포시 깔아준다.
- * 소스 코드는 절대 건드리지 않는다.
+ * 기존 프로젝트(현재 디렉터리)에 bc.config.json 과 필수 의존성을 추가한다.
+ * 기존 소스 코드는 건드리지 않는다.
  *
  * 흐름:
  *   1) 자동 감지(framework, styling, language, routing 등) 결과를 보여주고
@@ -145,6 +146,22 @@ export async function adoptCommand(opts = {}) {
   console.log(chalk.green(`\n  ✓ ${CONFIG_PATHS.projectFileName} 작성 완료.`));
   console.log(chalk.dim(`    ${targetFile}`));
 
+  const dependencies = await ensureRequiredDependencies({
+    cwd,
+    pkg: ctx.pkg,
+    framework: ctx.framework,
+    packageManager: ctx.packageManager,
+  });
+  if (dependencies.installed.length) {
+    console.log(
+      chalk.green(
+        `  ✓ 필수 의존성 설치 완료 (${dependencies.packageManager}): ${dependencies.installed.join(', ')}`,
+      ),
+    );
+  } else {
+    console.log(chalk.dim('  필수 의존성 유지 (이미 설치됨)'));
+  }
+
   // API 코드 컨벤션 .md 를 API 루트(src/api | src/lib/api)에 깐다 (이미 있으면 유지).
   try {
     const { relPath, written } = await scaffoldApiConventionDoc({

package/src/commands/chat.js

@@ -25,6 +25,7 @@ import {
 import { findLastRetryableUser, formatSessionList } from '../history/management.js';
 import { getCachedOpenApi } from '../openapi/cache.js';
 import { summarizeOpenApi } from '../openapi/summary.js';
+import { updateProjectLink } from '../config/projectLinks.js';
 
 /**
  * `bc chat`
@@ -330,7 +331,7 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
   }
   console.log(
     chalk.dim(
-      '  /history · /retry · /image <경로> · /paste · /clear-attach · /exit\n',
+      '  /history · /retry · /figma-link <url|off> · /openapi-link <url|off> · /image <경로> · /exit\n',
     ),
   );
 
@@ -425,6 +426,32 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       ask();
       continue;
     }
+    if (/^\/(figma-link|openapi-link)(\s|$)/.test(line)) {
+      const isFigma = line === '/figma-link' || line.startsWith('/figma-link ');
+      const kind = isFigma ? 'figma' : 'openapi';
+      const label = isFigma ? 'Figma' : 'OpenAPI';
+      const command = line.match(/^\/(figma-link|openapi-link)/)[1];
+      const arg = line.slice(command.length + 1).trim();
+      if (!arg) {
+        const current = isFigma ? cfg.effective.design?.figma : cfg.effective.api?.openapi;
+        console.log(chalk.dim(`  현재 ${label}: ${current ?? '(미설정)'}`));
+        console.log(chalk.dim(`  사용법: /${kind} <url|off>`));
+        ask();
+        continue;
+      }
+      try {
+        cfg = await updateProjectLink(cfg, kind, arg);
+        const value = isFigma ? cfg.effective.design?.figma : cfg.effective.api?.openapi;
+        system += value
+          ? `\n\n[프로젝트 설정 변경] ${label} 소스는 ${value} 이다. 이전 ${label} 링크와 요약은 무시하고 이 값을 사용하라.`
+          : `\n\n[프로젝트 설정 변경] ${label} 링크가 해제되었다. 이전 ${label} 링크와 요약은 사용하지 마라.`;
+        console.log(chalk.green(`  ${label} 링크를 ${value ? '변경했습니다: ' + value : '해제했습니다.'}`));
+      } catch (err) {
+        console.log(chalk.red('  ' + err.message));
+      }
+      ask();
+      continue;
+    }
     let retryContent = null;
     if (line === '/retry') {
       const retry = findLastRetryableUser(history);

package/src/commands/init.js

@@ -1,7 +1,13 @@
 import chalk from "chalk";
 
 import { createProject } from "../generators/createProject.js";
-import { askInitQuestions } from "../prompts/initPrompts.js";
+import { createMonorepo } from "../generators/createMonorepo.js";
+import { installMonorepoDeps } from "../generators/install.js";
+import {
+  askInitQuestions,
+  askProjectType,
+  askMonorepoQuestions,
+} from "../prompts/initPrompts.js";
 
 export async function initCommand() {
   console.log(
@@ -9,43 +15,14 @@ export async function initCommand() {
   );
 
   try {
-    const answers = await askInitQuestions();
+    const projectType = await askProjectType();
 
-    console.log(
-      chalk.dim(
-        `\n  ${answers.framework} 프로젝트를 생성하는 중... (${answers.projectName})\n`
-      )
-    );
-
-    await createProject({ ...answers, typescript: true });
-
-    console.log(
-      chalk.bold.green(
-        `\n  ✓ ${answers.projectName} 프로젝트가 생성되었습니다!\n`
-      )
-    );
-    console.log(chalk.yellow("  다음 명령어로 시작하세요:\n"));
-    console.log(chalk.white(`    cd ${answers.projectName}`));
-    console.log(chalk.white("    npm run dev\n"));
-
-    console.log(chalk.dim("  AI 어시스턴트:"));
-    if (answers.aiModel) {
-      console.log(
-        chalk.dim(
-          `    이 프로젝트의 기본 모델 = ${answers.aiModel} (bc.config.json 에 저장됨)`
-        )
-      );
-    } else {
-      console.log(
-        chalk.dim("    모델 미설정 — `bc config set-model` 로 나중에 지정")
-      );
+    if (projectType === "monorepo") {
+      await runMonorepoInit();
+      return;
     }
-    console.log(
-      chalk.dim(
-        "    API 키:  bc config set-key anthropic   (또는 ANTHROPIC_API_KEY 환경변수)"
-      )
-    );
-    console.log(chalk.dim("    실행:    bc chat\n"));
+
+    await runSingleInit();
   } catch (error) {
     if (error.code === "EEXIST") {
       console.error(
@@ -60,3 +37,75 @@ export async function initCommand() {
     process.exit(1);
   }
 }
+
+async function runSingleInit() {
+  const answers = await askInitQuestions();
+
+  console.log(
+    chalk.dim(
+      `\n  ${answers.framework} 프로젝트를 생성하는 중... (${answers.projectName})\n`
+    )
+  );
+
+  await createProject({ ...answers, typescript: true });
+
+  console.log(
+    chalk.bold.green(
+      `\n  ✓ ${answers.projectName} 프로젝트가 생성되었습니다!\n`
+    )
+  );
+  console.log(chalk.yellow("  다음 명령어로 시작하세요:\n"));
+  console.log(chalk.white(`    cd ${answers.projectName}`));
+  console.log(chalk.white("    npm run dev\n"));
+
+  printAiHints(answers.aiModel);
+}
+
+async function runMonorepoInit() {
+  const answers = await askMonorepoQuestions();
+
+  console.log(
+    chalk.dim(
+      `\n  모노레포 '${answers.projectName}' 생성 중... (scope: @${answers.scope}, 첫 앱: ${answers.framework} / apps/${answers.appName})\n`
+    )
+  );
+
+  const { root, scope, appName } = await createMonorepo({
+    ...answers,
+    typescript: true,
+  });
+
+  await installMonorepoDeps({ root, appPkgName: `@${scope}/${appName}` });
+
+  console.log(
+    chalk.bold.green(`\n  ✓ 모노레포 '${answers.projectName}' 가 생성되었습니다!\n`)
+  );
+  console.log(chalk.yellow("  다음 명령어로 시작하세요:\n"));
+  console.log(chalk.white(`    cd ${answers.projectName}`));
+  console.log(chalk.white("    pnpm install"));
+  console.log(chalk.white(`    pnpm ${appName}          # ${appName} 앱 실행\n`));
+  console.log(chalk.dim("  앱을 더 추가하려면 루트에서:  bc add\n"));
+
+  printAiHints(answers.aiModel);
+}
+
+function printAiHints(aiModel) {
+  console.log(chalk.dim("  AI 어시스턴트:"));
+  if (aiModel) {
+    console.log(
+      chalk.dim(
+        `    이 프로젝트의 기본 모델 = ${aiModel} (bc.config.json 에 저장됨)`
+      )
+    );
+  } else {
+    console.log(
+      chalk.dim("    모델 미설정 — `bc config set-model` 로 나중에 지정")
+    );
+  }
+  console.log(
+    chalk.dim(
+      "    API 키:  bc config set-key anthropic   (또는 ANTHROPIC_API_KEY 환경변수)"
+    )
+  );
+  console.log(chalk.dim("    실행:    bc chat\n"));
+}

package/src/config/projectLinks.js

@@ -0,0 +1,49 @@
+import { parseFigmaUrl } from '../figma/url.js';
+import { saveProjectConfig } from './index.js';
+
+function normalizeUrl(raw, kind) {
+  const value = raw.trim();
+  if (['off', 'none', 'clear'].includes(value.toLowerCase())) return null;
+
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${kind} 링크가 올바른 URL이 아닙니다.`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error(`${kind} 링크는 http 또는 https URL이어야 합니다.`);
+  }
+  if (kind === 'Figma' && !parseFigmaUrl(value)) {
+    throw new Error('지원하는 Figma file/design/proto 링크가 아닙니다.');
+  }
+  return value;
+}
+
+export async function updateProjectLink(cfg, kind, rawValue) {
+  if (!cfg.paths.projectFile) {
+    throw new Error('bc.config.json이 없습니다. 먼저 `bc adopt` 또는 `bc init`을 실행하세요.');
+  }
+
+  const value = normalizeUrl(rawValue, kind === 'figma' ? 'Figma' : 'OpenAPI');
+  const project = {
+    ...cfg.project,
+    design: { ...(cfg.project.design ?? {}) },
+    api: { ...(cfg.project.api ?? {}) },
+  };
+
+  if (kind === 'figma') project.design.figma = value;
+  else project.api.openapi = value;
+
+  await saveProjectConfig(cfg.paths.projectFile, project);
+
+  return {
+    ...cfg,
+    project,
+    effective: {
+      ...cfg.effective,
+      design: project.design,
+      api: project.api,
+    },
+  };
+}

package/src/context/monorepo.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 모노레포(pnpm workspace) 관련 감지/유틸.
+ *
+ * - detectMonorepoRoot: 현재 위치에서 위로 올라가며 pnpm-workspace.yaml 을 찾는다.
+ * - detectScope:        기존 워크스페이스 패키지 이름에서 `@scope` 를 추출한다.
+ * - deriveScope:        모노레포 이름에서 scope 후보를 만든다 (marketd-frontend → marketd).
+ */
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonSafe(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * pnpm-workspace.yaml 을 기준으로 모노레포 루트를 찾는다.
+ * @returns {Promise<string|null>} 루트 절대경로 또는 null
+ */
+export async function detectMonorepoRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  // 파일시스템 루트까지 올라간다.
+  while (true) {
+    if (await exists(path.join(dir, 'pnpm-workspace.yaml'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * 모노레포에서 사용 중인 npm scope (`@marketd` 의 marketd) 를 추론한다.
+ * apps/*, packages/* 의 package.json name 에서 우선 추출하고,
+ * 실패하면 루트 package.json name 을 fallback 으로 쓴다.
+ */
+export async function detectScope(root) {
+  const candidateDirs = ['packages', 'apps'];
+  for (const base of candidateDirs) {
+    const baseDir = path.join(root, base);
+    let entries = [];
+    try {
+      entries = await fs.readdir(baseDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const pkg = await readJsonSafe(path.join(baseDir, entry.name, 'package.json'));
+      const name = pkg?.name;
+      if (typeof name === 'string' && name.startsWith('@')) {
+        const scope = name.slice(1).split('/')[0];
+        if (scope) return scope;
+      }
+    }
+  }
+
+  const rootPkg = await readJsonSafe(path.join(root, 'package.json'));
+  if (rootPkg?.name) return deriveScope(rootPkg.name);
+  return 'workspace';
+}
+
+/**
+ * 모노레포 이름에서 scope 를 뽑아낸다.
+ *  marketd-frontend  → marketd
+ *  acme-fe           → acme
+ *  @acme/repo        → acme
+ */
+export function deriveScope(name) {
+  let base = String(name || '').trim();
+  if (base.startsWith('@')) base = base.slice(1).split('/')[0];
+  base = base
+    .replace(/-(frontend|front|fe|monorepo|mono|workspace|repo)$/i, '')
+    .replace(/[^a-z0-9-]/gi, '')
+    .toLowerCase();
+  return base || 'workspace';
+}
+
+/**
+ * apps/<name> 이 이미 존재하는지 확인.
+ */
+export async function appExists(root, appName) {
+  return exists(path.join(root, 'apps', appName));
+}
+
+export { exists as pathExists, readJsonSafe };