@simplysm/sd-cli 14.0.11 → 14.0.13

package/src/capacitor/capacitor.ts

@@ -5,7 +5,7 @@ import { symlink } from "fs/promises";
 import { createRequire } from "module";
 import { cpx, fsx, pathx } from "@simplysm/core-node";
 import { env } from "@simplysm/core-common";
-import { consola } from "consola";
+import { consola, LogLevels } from "consola";
 import type { SdCapacitorConfig } from "../sd-config.types.js";
 
 /**
@@ -91,9 +91,7 @@ export class Capacitor {
       const platforms = Object.keys(config.platform);
       for (const p of platforms) {
         if (p !== "android") {
-          throw new CapacitorConfigError(
-            `지원하지 않는 플랫폼입니다: ${p} (현재 android만 지원)`,
-          );
+          throw new CapacitorConfigError(`지원하지 않는 플랫폼입니다: ${p} (현재 android만 지원)`);
         }
       }
     }
@@ -109,47 +107,65 @@ export class Capacitor {
    * 5. cap sync 또는 cap copy 실행
    */
   async initialize(): Promise<void> {
+    Capacitor._logger.debug("initialize 시작");
     await this._acquireLock();
 
     try {
       // 외부 도구 검증
+      Capacitor._logger.debug("외부 도구 검증 시작");
       await this._validateTools();
+      Capacitor._logger.debug("외부 도구 검증 완료");
 
       // 1. Capacitor 프로젝트 초기화
+      Capacitor._logger.debug("Capacitor 프로젝트 초기화 시작");
       const changed = await this._initCap();
+      Capacitor._logger.debug(`Capacitor 프로젝트 초기화 완료 (changed: ${changed})`);
 
       // 2. Capacitor 설정 파일 생성
+      Capacitor._logger.debug("Capacitor 설정 파일 생성 시작");
       await this._writeCapConf();
+      Capacitor._logger.debug("Capacitor 설정 파일 생성 완료");
 
       // 3. 플랫폼 관리 (멱등성: 이미 존재하면 스킵)
+      Capacitor._logger.debug("플랫폼 추가 시작");
       await this._addPlatforms();
+      Capacitor._logger.debug("플랫폼 추가 완료");
 
       // 4. 아이콘 처리
+      Capacitor._logger.debug("아이콘 처리 시작");
       await this._setupIcon();
+      Capacitor._logger.debug("아이콘 처리 완료");
 
       // 5. Android 네이티브 설정 구성
       if (this._platforms.includes("android")) {
+        Capacitor._logger.debug("Android 네이티브 설정 시작");
         await this._configureAndroid();
+        Capacitor._logger.debug("Android 네이티브 설정 완료");
       }
 
       // 6. 웹 에셋 동기화
       if (changed) {
+        Capacitor._logger.debug("cap sync 시작 (의존성 변경됨)");
         await this._execCap(["sync"]);
+        Capacitor._logger.debug("cap sync 완료");
       } else {
+        Capacitor._logger.debug("cap copy 시작");
         await this._execCap(["copy"]);
+        Capacitor._logger.debug("cap copy 완료");
       }
     } finally {
       await this._releaseLock();
+      Capacitor._logger.debug("initialize 완료");
     }
   }
 
   //#region Private - 명령어 실행
 
   /**
-   * Capacitor CLI 명령어를 npx로 실행
+   * Capacitor CLI 명령어를 pnpm exec로 실행
    */
   private async _execCap(args: string[]): Promise<string> {
-    return this._exec("npx", ["cap", ...args], this._capPath);
+    return this._exec("pnpm", ["exec", "cap", ...args], this._capPath);
   }
 
   /**
@@ -157,7 +173,11 @@ export class Capacitor {
    */
   private async _exec(command: string, args: string[], cwd: string): Promise<string> {
     Capacitor._logger.debug(`명령어 실행: ${command} ${args.join(" ")}`);
-    const { stdout } = await cpx.exec(command, args, { cwd });
+    const isDebug = consola.level >= LogLevels.debug;
+    const { stdout } = await cpx.spawn(command, args, {
+      cwd,
+      ...(isDebug ? { stdio: ["ignore", "inherit", "inherit"] } : {}),
+    });
     Capacitor._logger.debug(`실행 결과: ${stdout}`);
     return stdout;
   }
@@ -215,6 +235,7 @@ export class Capacitor {
           "2. ANDROID_HOME 또는 ANDROID_SDK_ROOT 환경 변수를 설정하세요.",
       );
     }
+    Capacitor._logger.debug(`Android SDK 경로: ${sdkPath}`);
 
     // Java 확인 (android 플랫폼인 경우에만)
     if (this._platforms.includes("android")) {
@@ -223,6 +244,8 @@ export class Capacitor {
         Capacitor._logger.warn(
           "Java 21을 찾을 수 없습니다. Gradle이 내장 JDK를 사용하거나 빌드가 실패할 수 있습니다.",
         );
+      } else {
+        Capacitor._logger.debug(`Java 21 경로: ${javaPath}`);
       }
     }
   }
@@ -235,36 +258,47 @@ export class Capacitor {
    * Capacitor 프로젝트 기본 초기화 (package.json, npm install, cap init)
    */
   private async _initCap(): Promise<boolean> {
+    Capacitor._logger.debug("package.json 설정 시작");
     const { depChanged, workspacePlugins } = await this._setupNpmConf();
     const nodeModulesExists = await fsx.exists(pathx.posixResolve(this._capPath, "node_modules"));
+    Capacitor._logger.debug(`depChanged: ${depChanged}, nodeModulesExists: ${nodeModulesExists}`);
 
     if (!depChanged && nodeModulesExists) {
       // 의존성 미변경이어도 workspace 플러그인 symlink는 항상 갱신
+      Capacitor._logger.debug("의존성 변경 없음, workspace 플러그인 symlink만 갱신");
       await this._linkWorkspacePlugins(workspacePlugins);
       return false;
     }
 
-    // npm install
-    const installResult = await this._exec("npm", ["install"], this._capPath);
-    Capacitor._logger.debug(`npm install 완료: ${installResult}`);
+    // pnpm-workspace.yaml 생성 (상위 workspace 탐색 차단)
+    const workspaceYamlPath = pathx.posixResolve(this._capPath, "pnpm-workspace.yaml");
+    if (!(await fsx.exists(workspaceYamlPath))) {
+      await fsx.write(workspaceYamlPath, "");
+    }
+    const lockfilePath = pathx.posixResolve(this._capPath, "pnpm-lock.yaml");
+    if (!(await fsx.exists(lockfilePath))) {
+      await fsx.write(lockfilePath, "");
+    }
+
+    // pnpm install + 빌드 스크립트 승인
+    Capacitor._logger.debug("pnpm install 시작");
+    await this._exec("pnpm", ["install"], this._capPath);
+    await this._exec("pnpm", ["approve-builds", "--all"], this._capPath);
+    Capacitor._logger.debug("pnpm install 완료");
 
     // workspace 플러그인 symlink
+    Capacitor._logger.debug("workspace 플러그인 symlink 시작");
     await this._linkWorkspacePlugins(workspacePlugins);
+    Capacitor._logger.debug("workspace 플러그인 symlink 완료");
 
     // 멱등성: capacitor.config.ts가 없을 때만 cap init 실행
     const configPath = pathx.posixResolve(this._capPath, "capacitor.config.ts");
     if (!(await fsx.exists(configPath))) {
+      Capacitor._logger.debug("cap init 시작");
       await this._execCap(["init", this._config.appId, this._config.appId]);
+      Capacitor._logger.debug("cap init 완료");
     }
 
-    // 기본 www/index.html 생성
-    const wwwPath = pathx.posixResolve(this._capPath, "www");
-    await fsx.mkdir(wwwPath);
-    await fsx.write(
-      pathx.posixResolve(wwwPath, "index.html"),
-      "<!DOCTYPE html><html><head></head><body></body></html>",
-    );
-
     return true;
   }
 
@@ -465,8 +499,9 @@ export default config;
 
       // capacitor-assets로 모든 해상도 아이콘/스플래시 생성
       await this._exec(
-        "npx",
+        "pnpm",
         [
+          "exec",
           "capacitor-assets",
           "generate",
           "--iconBackgroundColor",
@@ -500,10 +535,29 @@ export default config;
       throw new Error(`Android 프로젝트 디렉토리를 찾을 수 없습니다: ${androidPath}`);
     }
 
+    Capacitor._logger.debug("JAVA_HOME 설정 시작");
     await this._configureAndroidJavaHomePath(androidPath);
+    Capacitor._logger.debug("JAVA_HOME 설정 완료");
+
+    Capacitor._logger.debug("Android SDK 경로 설정 시작");
     await this._configureAndroidSdkPath(androidPath);
+    Capacitor._logger.debug("Android SDK 경로 설정 완료");
+
+    Capacitor._logger.debug("AndroidManifest.xml 설정 시작");
     await this._configureAndroidManifest(androidPath);
+    Capacitor._logger.debug("AndroidManifest.xml 설정 완료");
+
+    Capacitor._logger.debug("루트 build.gradle Kotlin 플러그인 설정 시작");
+    await this._configureAndroidRootBuildGradle(androidPath);
+    Capacitor._logger.debug("루트 build.gradle Kotlin 플러그인 설정 완료");
+
+    Capacitor._logger.debug("build.gradle 설정 시작");
     await this._configureAndroidBuildGradle(androidPath);
+    Capacitor._logger.debug("build.gradle 설정 완료");
+
+    Capacitor._logger.debug("styles.xml 설정 시작");
+    await this._configureAndroidStyles(androidPath);
+    Capacitor._logger.debug("styles.xml 설정 완료");
   }
 
   /**
@@ -574,7 +628,9 @@ export default config;
    * Android SDK 경로 탐색
    */
   private async _findAndroidSdk(): Promise<string | undefined> {
-    const androidHome = (env["ANDROID_HOME"] as string | undefined) ?? (env["ANDROID_SDK_ROOT"] as string | undefined);
+    const androidHome =
+      (env["ANDROID_HOME"] as string | undefined) ??
+      (env["ANDROID_SDK_ROOT"] as string | undefined);
     if (androidHome != null && (await fsx.exists(androidHome))) {
       return androidHome;
     }
@@ -670,6 +726,28 @@ export default config;
     await fsx.write(manifestPath, content);
   }
 
+  /**
+   * 루트 build.gradle에 Kotlin Gradle 플러그인 classpath 추가
+   */
+  private async _configureAndroidRootBuildGradle(androidPath: string): Promise<void> {
+    const rootBuildGradlePath = pathx.posixResolve(androidPath, "build.gradle");
+
+    if (!(await fsx.exists(rootBuildGradlePath))) {
+      Capacitor._logger.warn(`루트 build.gradle 파일을 찾을 수 없습니다: ${rootBuildGradlePath}`);
+      return;
+    }
+
+    let content = await fsx.read(rootBuildGradlePath);
+
+    if (!content.includes("kotlin-gradle-plugin")) {
+      content = content.replace(
+        /classpath 'com\.android\.tools\.build:gradle:[^']+'/,
+        `$&\n        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.20'`,
+      );
+      await fsx.write(rootBuildGradlePath, content);
+    }
+  }
+
   /**
    * build.gradle 수정 (서명 설정 제외)
    */
@@ -710,6 +788,51 @@ export default config;
     await fsx.write(buildGradlePath, content);
   }
 
+  /**
+   * styles.xml의 스플래시 테마 수정
+   *
+   * 1. Theme.SplashScreen parent → Theme.AppCompat.DayNight.NoActionBar
+   *    Theme.SplashScreen은 android:windowBackground에 compat_splash_screen을 설정하여
+   *    android:background(@drawable/splash)와 이중 표시를 발생시킨다.
+   *    installSplashScreen()을 호출하지 않으므로 Theme.SplashScreen 기능이 불필요하다.
+   *
+   * 2. android:background → android:windowBackground
+   *    android:background는 View 레벨 속성으로 AppCompat 뷰 계층의 여러 View에 상속되어
+   *    동일한 splash 로고가 다중 레이어에 중복 렌더링된다.
+   *    android:windowBackground는 Window의 DecorView에만 적용되어 단일 렌더링을 보장한다.
+   */
+  private async _configureAndroidStyles(androidPath: string): Promise<void> {
+    const stylesPath = pathx.posixResolve(androidPath, "app/src/main/res/values/styles.xml");
+
+    if (!(await fsx.exists(stylesPath))) {
+      Capacitor._logger.warn(`styles.xml 파일을 찾을 수 없습니다: ${stylesPath}`);
+      return;
+    }
+
+    let content = await fsx.read(stylesPath);
+    let changed = false;
+
+    if (content.includes('parent="Theme.SplashScreen"')) {
+      content = content.replace(
+        'parent="Theme.SplashScreen"',
+        'parent="Theme.AppCompat.DayNight.NoActionBar"',
+      );
+      changed = true;
+    }
+
+    if (content.includes('"android:background">@drawable/splash')) {
+      content = content.replace(
+        '"android:background">@drawable/splash',
+        '"android:windowBackground">@drawable/splash',
+      );
+      changed = true;
+    }
+
+    if (changed) {
+      await fsx.write(stylesPath, content);
+    }
+  }
+
   //#endregion
 
   //#region Public — 기기 실행
@@ -719,28 +842,35 @@ export default config;
    *
    * 1. capacitor.config.ts에 server.url 설정 (Hot Reload용)
    * 2. cap copy — 웹 에셋 동기화
-   * 3. cap run — 기기에서 앱 실행 (실패 시 adb kill-server 후 1회 재시도)
+   * 3. cap run — 기기에서 앱 실행
    */
   async run(url: string): Promise<void> {
+    Capacitor._logger.debug(`server.url 설정: ${url}`);
     await this._updateServerUrl(url);
 
     for (const platform of this._platforms) {
+      Capacitor._logger.debug(`[${platform}] cap copy 시작`);
       await this._execCap(["copy", platform]);
+      Capacitor._logger.debug(`[${platform}] cap copy 완료`);
 
       try {
+        Capacitor._logger.debug(`[${platform}] cap run 시작`);
         await this._execCap(["run", platform]);
+        Capacitor._logger.debug(`[${platform}] cap run 완료`);
       } catch (err) {
         if (platform === "android") {
-          Capacitor._logger.warn("cap run 실패. adb kill-server 후 재시도합니다.");
+          Capacitor._logger.debug(`[${platform}] adb kill-server 시작`);
           try {
             await this._exec("adb", ["kill-server"], this._capPath);
-          } catch {
-            // adb kill-server 실패는 무시
+            Capacitor._logger.debug(`[${platform}] adb kill-server 완료`);
+          } catch (adbErr) {
+            const adbErrMsg = adbErr instanceof Error ? adbErr.message : String(adbErr);
+            Capacitor._logger.debug(
+              `[${platform}] adb kill-server 실패 (무시): ${adbErrMsg}`,
+            );
           }
-          await this._execCap(["run", platform]);
-        } else {
-          throw err;
         }
+        throw err;
       }
     }
   }
@@ -779,30 +909,40 @@ export default config;
    * 4. 빌드 산출물 복사
    */
   async build(outPath: string): Promise<void> {
+    Capacitor._logger.debug("build 시작");
+
     // 1. 웹 에셋 동기화
+    Capacitor._logger.debug("cap copy 시작");
     await this._execCap(["copy"]);
+    Capacitor._logger.debug("cap copy 완료");
 
     // 2. 빌드 타입 결정
     const isDebug = this._config.debug === true;
     const isBundle = this._config.platform?.android?.bundle === true;
     const buildType = isDebug ? "debug" : "release";
+    Capacitor._logger.debug(`빌드 타입: ${buildType}, bundle: ${isBundle}`);
 
     // 3. 서명 설정
     const signConfig = this._config.platform?.android?.sign;
     if (!isDebug && signConfig != null) {
-      await this._configureSigningConfig(
-        pathx.posixResolve(this._capPath, "android"),
-        signConfig,
-      );
+      Capacitor._logger.debug("서명 설정 시작");
+      await this._configureSigningConfig(pathx.posixResolve(this._capPath, "android"), signConfig);
+      Capacitor._logger.debug("서명 설정 완료");
     } else if (!isDebug) {
       Capacitor._logger.warn("서명 설정이 없어 unsigned 빌드가 생성됩니다.");
     }
 
     // 4. Gradle 빌드
+    Capacitor._logger.debug("Gradle 빌드 시작");
     await this._buildAndroid(buildType, isBundle);
+    Capacitor._logger.debug("Gradle 빌드 완료");
 
     // 5. 빌드 산출물 복사
+    Capacitor._logger.debug("빌드 산출물 복사 시작");
     await this._copyBuildOutput(outPath, buildType, isBundle);
+    Capacitor._logger.debug("빌드 산출물 복사 완료");
+
+    Capacitor._logger.debug("build 완료");
   }
 
   //#endregion
@@ -833,8 +973,9 @@ export default config;
     if (content.includes("signingConfigs")) return;
 
     const storeType = sign.keystoreType ?? "jks";
-    const escapedStorePassword = sign.storePassword.replace(/'/g, "\\'");
-    const escapedKeyPassword = sign.password.replace(/'/g, "\\'");
+    const escapeGroovy = (s: string) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    const escapedStorePassword = escapeGroovy(sign.storePassword);
+    const escapedKeyPassword = escapeGroovy(sign.password);
 
     const signingBlock = `    signingConfigs {
         release {
@@ -848,7 +989,7 @@ export default config;
 `;
 
     // signingConfigs 블록을 buildTypes 앞에 삽입
-    content = content.replace(/(\s*buildTypes\s*\{)/, `${signingBlock}$1`);
+    content = content.replace(/(\s*buildTypes\s*\{)/, (match) => `\n${signingBlock}${match}`);
 
     // buildTypes.release에 signingConfig 추가
     content = content.replace(
@@ -874,11 +1015,15 @@ export default config;
 
     const androidPath = pathx.posixResolve(this._capPath, "android");
     const isWindows = process.platform === "win32";
-    const gradlew = isWindows
-      ? pathx.posixResolve(androidPath, "gradlew.bat")
-      : pathx.posixResolve(androidPath, "gradlew");
 
-    await this._exec(gradlew, [gradleTask, "--no-daemon"], androidPath);
+    if (isWindows) {
+      Capacitor._logger.debug(`Gradle 실행: cmd /c gradlew.bat ${gradleTask}`);
+      await this._exec("cmd", ["/c", "gradlew.bat", gradleTask, "--no-daemon"], androidPath);
+    } else {
+      const gradlew = pathx.posixResolve(androidPath, "gradlew");
+      Capacitor._logger.debug(`Gradle 실행: ${gradlew} ${gradleTask}`);
+      await this._exec(gradlew, [gradleTask, "--no-daemon"], androidPath);
+    }
   }
 
   /**
@@ -899,11 +1044,13 @@ export default config;
     );
 
     // 빌드 산출물 찾기
+    Capacitor._logger.debug(`빌드 산출물 탐색: ${androidBuildPath}`);
     const candidates = await fsx.glob(pathx.posixResolve(androidBuildPath, `app-*.${ext}`));
     if (candidates.length === 0) {
       throw new Error(`빌드 산출물을 찾을 수 없습니다: ${androidBuildPath}`);
     }
     const builtFile = candidates[0];
+    Capacitor._logger.debug(`빌드 산출물: ${builtFile}`);
     const isUnsigned = builtFile.includes("unsigned");
 
     // 출력 디렉토리 생성

package/src/commands/build.ts

@@ -4,17 +4,10 @@ import {
 } from "../orchestrators/BuildOrchestrator";
 
 /**
- * Run production build.
+ * BuildOrchestrator를 통해 프로덕션 빌드를 실행한다.
  *
- * - Load `sd.config.ts` to check build target info per package (required)
- * - Run lint
- * - Clean dist folder (clean build)
- * - `node`/`browser`/`neutral` target: esbuild JS build + dts generation (with type check)
- * - `client` target: Vite production build + typecheck (dts not needed)
- * - Set `process.exitCode = 1` if any step fails
- *
- * @param options - build execution options
- * @returns resolves on completion
+ * @param options - 빌드 실행 옵션
+ * @returns 완료 시 resolve
  */
 export async function runBuild(options: BuildOrchestratorOptions): Promise<void> {
   const orchestrator = new BuildOrchestrator(options);

package/src/commands/check.ts

@@ -34,7 +34,7 @@ async function spawnVitest(targets: string[]): Promise<CheckResult> {
     const args = ["vitest", ...targets, "--run"];
     logger.debug("vitest 실행", { args });
     logger.start("테스트 실행 중...");
-    const result = await cpx.exec("pnpm", args, { cwd: process.cwd(), reject: false });
+    const result = await cpx.spawn("pnpm", args, { cwd: process.cwd(), reject: false });
     const output = result.stdout + result.stderr;
     const code = result.exitCode;
 
@@ -188,7 +188,7 @@ export async function runCheck(options: CheckOptions): Promise<void> {
   const results = await Promise.allSettled(tasks);
   logger.success("체크 실행 완료");
 
-  // 결과 수집 (flatten arrays from executeTypecheck)
+  // 결과 수집 (executeTypecheck 배열 평탄화)
   const checkResults: CheckResult[] = results.flatMap((r) => {
     if (r.status === "fulfilled") {
       const value = r.value;
@@ -211,7 +211,7 @@ export async function runCheck(options: CheckOptions): Promise<void> {
     process.stdout.write(formatSection(result));
   }
 
-  // SUMMARY
+  // 요약
   const failed = checkResults.filter((r) => !r.success);
   const totalErrors = checkResults.reduce((sum, r) => sum + r.errorCount, 0);
   const totalWarnings = checkResults.reduce((sum, r) => sum + r.warningCount, 0);

package/src/commands/dev.ts

@@ -4,16 +4,10 @@ import {
 } from "../orchestrators/DevWatchOrchestrator";
 
 /**
- * Run Server packages in development mode.
+ * DevWatchOrchestrator를 통해 서버 패키지를 개발 모드로 실행한다.
  *
- * - Load `sd.config.ts` to check build target info per package (required)
- * - `server` target: Server Build Worker + Server Runtime Worker
- * - `client` target: recognized but skipped (BuildEngine not yet implemented)
- * - Library packages excluded from dev mode
- * - Terminate with SIGINT/SIGTERM signals
- *
- * @param options - dev execution options (targets, options)
- * @returns resolves on termination signal
+ * @param options - 개발 모드 실행 옵션 (targets, options)
+ * @returns 종료 시그널 수신 시 resolve
  */
 export async function runDev(options: Omit<DevWatchOrchestratorOptions, "mode">): Promise<void> {
   const orchestrator = new DevWatchOrchestrator({ mode: "dev", ...options });

package/src/commands/device.ts

@@ -14,10 +14,10 @@ export interface DeviceOptions {
 }
 
 /**
- * Run native app on device/desktop.
+ * 네이티브 앱을 디바이스/데스크톱에서 실행한다.
  *
- * - Electron config takes priority over Capacitor when both are present.
- * - If --url is not provided, auto-generates from sd.config.ts server port.
+ * - Electron 설정이 Capacitor보다 우선한다.
+ * - --url이 제공되지 않으면 sd.config.ts의 서버 포트로 자동 생성한다.
  */
 export async function runDevice(options: DeviceOptions): Promise<void> {
   const cwd = process.cwd();
@@ -34,7 +34,7 @@ export async function runDevice(options: DeviceOptions): Promise<void> {
   const clientConfig = pkgConfig;
   const pkgDir = pathx.posixResolve(cwd, "packages", options.package);
 
-  // Determine server URL
+  // 서버 URL 결정
   let serverUrl = options.url;
   if (serverUrl == null) {
     if (typeof clientConfig.server === "number") {
@@ -46,7 +46,7 @@ export async function runDevice(options: DeviceOptions): Promise<void> {
     }
   }
 
-  // Electron takes priority over Capacitor (v13 behavior)
+  // Electron이 Capacitor보다 우선
   if (clientConfig.electron != null) {
     logger.start(`${options.package} (electron) 실행 중...`);
     const electron = await Electron.create(pkgDir, clientConfig.electron, clientConfig.exclude);

package/src/commands/publish.ts

@@ -144,7 +144,7 @@ async function ensureSshAuth(
   const privateKeyData = fs.readFileSync(keyPath);
   const publicKey = fs.readFileSync(pubKeyPath, "utf-8").trim();
 
-  // 개인키가 암호화되어 있는지 확인
+  // 개인키 파싱 시도 (암호화 또는 형식 오류 시 Error 반환)
   const parsed = utils.parseKey(privateKeyData);
   const isKeyEncrypted = parsed instanceof Error;
   const sshAgent = process.env["SSH_AUTH_SOCK"];
@@ -352,7 +352,7 @@ async function publishPackage(
       logger.debug(`[${pkgName}] pnpm ${args.join(" ")}`);
     }
 
-    await cpx.exec("pnpm", args, { cwd: pkgPath });
+    await cpx.spawn("pnpm", args, { cwd: pkgPath });
   } else if (publishConfig.type === "local-directory") {
     // 로컬 디렉토리에 복사
     const targetPath = replaceEnvVariables(publishConfig.path, version, projectPath);
@@ -466,7 +466,7 @@ async function computePublishLevels(
  * 2. 버전 업그레이드 (package.json + 템플릿)
  * 3. 빌드
  * 4. Git commit/tag/push (변경된 파일만 명시적으로 스테이징)
- * 5. pnpm 배포
+ * 5. 패키지 배포 (npm/로컬 디렉토리/스토리지)
  * 6. postPublish (실패해도 계속 진행)
  */
 export async function runPublish(options: PublishOptions): Promise<void> {
@@ -559,18 +559,18 @@ export async function runPublish(options: PublishOptions): Promise<void> {
   if (publishPackages.some((p) => p.config.type === "npm")) {
     logger.debug("npm 인증 검증 중...");
     try {
-      const { stdout: whoami } = await cpx.exec("npm", ["whoami"]);
+      const { stdout: whoami } = await cpx.spawn("npm", ["whoami"]);
       if (whoami.trim() === "") {
         throw new Error("npm 로그인 정보를 찾을 수 없습니다.");
       }
       logger.debug(`npm 로그인 확인됨: ${whoami.trim()}`);
-    } catch (err) {
-      logger.error(`npm whoami 실패:`, err);
-      /*logger.error(
-        "npm token is invalid or expired.\n" +
-          "Create a Granular Access Token at https://www.npmjs.com/settings/~/tokens, then:\n" +
-          "  npm config set //registry.npmjs.org/:_authToken <token>",
-      );*/
+    } catch {
+      logger.error(
+        "npm 인증 실패. 로그인 상태를 확인해주세요.\n" +
+          "  npm whoami              # 현재 로그인 확인\n" +
+          "  npm login               # 로그인\n" +
+          "  npm config set //registry.npmjs.org/:_authToken <token>  # 토큰 직접 설정",
+      );
       process.exitCode = 1;
       return;
     }
@@ -589,19 +589,23 @@ export async function runPublish(options: PublishOptions): Promise<void> {
   if (!noBuild && hasGit) {
     logger.debug("git 커밋 상태 확인 중...");
     try {
-      const { stdout: diff } = await cpx.exec("git", ["diff", "--name-only"]);
-      const { stdout: stagedDiff } = await cpx.exec("git", ["diff", "--cached", "--name-only"]);
+      const { stdout: diff } = await cpx.spawn("git", ["diff", "--name-only"]);
+      const { stdout: stagedDiff } = await cpx.spawn("git", ["diff", "--cached", "--name-only"]);
 
       if (diff.trim() !== "" || stagedDiff.trim() !== "") {
         logger.info("커밋되지 않은 변경사항 감지. claude로 자동 커밋 시도 중...");
         try {
-          await cpx.exec("claude", [
-            "-p",
-            "/sd-commit all",
-            "--dangerously-skip-permissions",
-            "--model",
-            "haiku",
-          ], { stdio: "inherit" });
+          await cpx.spawn(
+            "claude",
+            ["-p", "/sd-commit", "--dangerously-skip-permissions", "--model", "haiku"],
+            {
+              stdio: "inherit",
+              env: {
+                ...process.env,
+                MCP_CONNECTION_NONBLOCKING: "true",
+              },
+            },
+          );
         } catch (e) {
           throw new Error(
             "자동 커밋에 실패했습니다. 수동으로 커밋 후 다시 시도해주세요.\n" +
@@ -683,11 +687,11 @@ export async function runPublish(options: PublishOptions): Promise<void> {
       } else {
         logger.debug("Git commit/tag/push...");
         try {
-          await cpx.exec("git", ["add", ..._changedFiles]);
-          await cpx.exec("git", ["commit", "-m", `v${version}`]);
-          await cpx.exec("git", ["tag", "-a", `v${version}`, "-m", `v${version}`]);
-          await cpx.exec("git", ["push"]);
-          await cpx.exec("git", ["push", "--tags"]);
+          await cpx.spawn("git", ["add", ..._changedFiles]);
+          await cpx.spawn("git", ["commit", "-m", `v${version}`]);
+          await cpx.spawn("git", ["tag", "-a", `v${version}`, "-m", `v${version}`]);
+          await cpx.spawn("git", ["push"]);
+          await cpx.spawn("git", ["push", "--tags"]);
           logger.debug("Git 작업 완료");
         } catch (err) {
           logger.error(
@@ -806,7 +810,7 @@ export async function runPublish(options: PublishOptions): Promise<void> {
           logger.info(`[DRY-RUN] 실행 예정: ${cmd} ${args.join(" ")}`);
         } else {
           logger.debug(`실행 중: ${cmd} ${args.join(" ")}`);
-          await cpx.exec(cmd, args, { cwd });
+          await cpx.spawn(cmd, args, { cwd });
         }
       } catch (err) {
         // postPublish 실패 시 경고만 출력 (배포 롤백 불가)