@simplysm/sd-cli 13.0.100 → 14.0.4

package/src/capacitor/capacitor.ts

@@ -1,13 +1,16 @@
+import fs from "node:fs";
+import { existsSync } from "node:fs";
 import path from "path";
+import { execa } from "execa";
+import { symlink } from "fs/promises";
+import { createRequire } from "module";
 import { fsx } from "@simplysm/core-node";
 import { env } from "@simplysm/core-common";
 import { consola } from "consola";
-import sharp from "sharp";
-import type { SdCapacitorConfig } from "../sd-config.types";
-import { execa } from "execa";
+import type { SdCapacitorConfig } from "../sd-config.types.js";
 
 /**
- * package.json type
+ * package.json 타입
  */
 interface NpmConfig {
   name: string;
@@ -19,7 +22,7 @@ interface NpmConfig {
 }
 
 /**
- * Configuration validation error
+ * 설정 검증 에러
  */
 class CapacitorConfigError extends Error {
   constructor(message: string) {
@@ -29,18 +32,14 @@ class CapacitorConfigError extends Error {
 }
 
 /**
- * Capacitor project management class
+ * Capacitor 프로젝트 관리 클래스
  *
- * - Initialize Capacitor project
- * - Build Android APK/AAB
- * - Run app on device
+ * - Capacitor 프로젝트 초기화
+ * - Android 네이티브 설정 구성
  */
 export class Capacitor {
-  private static readonly _ANDROID_KEYSTORE_FILE_NAME = "android.keystore";
   private static readonly _LOCK_FILE_NAME = ".capacitor.lock";
   private static readonly _logger = consola.withTag("sd:cli:capacitor");
-  private static readonly _utf8Decoder = new TextDecoder("utf-8", { fatal: true });
-  private static readonly _fallbackDecoder = new TextDecoder("euc-kr");
 
   private readonly _capPath: string;
   private readonly _platforms: string[];
@@ -58,14 +57,13 @@ export class Capacitor {
   }
 
   /**
-   * Create Capacitor instance (with configuration validation)
+   * Capacitor 인스턴스 생성 (설정 검증 포함)
    */
   static async create(
     pkgPath: string,
     config: SdCapacitorConfig,
     exclude?: string[],
   ): Promise<Capacitor> {
-    // F5: validate runtime configuration
     Capacitor._validateConfig(config);
 
     const npmConfig = await fsx.readJson<NpmConfig>(path.resolve(pkgPath, "package.json"));
@@ -73,158 +71,69 @@ export class Capacitor {
   }
 
   /**
-   * F5: Validate configuration
+   * 설정 검증
    */
   private static _validateConfig(config: SdCapacitorConfig): void {
     if (typeof config.appId !== "string" || config.appId.trim() === "") {
-      throw new CapacitorConfigError("capacitor.appId is required.");
+      throw new CapacitorConfigError("capacitor.appId가 필요합니다.");
     }
     if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/i.test(config.appId)) {
-      throw new CapacitorConfigError(`capacitor.appId format is invalid: ${config.appId}`);
+      throw new CapacitorConfigError(`capacitor.appId 형식이 올바르지 않습니다: ${config.appId}`);
     }
     if (typeof config.appName !== "string" || config.appName.trim() === "") {
-      throw new CapacitorConfigError("capacitor.appName is required.");
+      throw new CapacitorConfigError("capacitor.appName이 필요합니다.");
     }
     if (!/^[\p{L}\p{N} \-]+$/u.test(config.appName)) {
-      throw new CapacitorConfigError(`capacitor.appName contains invalid characters: ${config.appName}`);
+      throw new CapacitorConfigError(
+        `capacitor.appName에 허용되지 않는 문자가 포함되어 있습니다: ${config.appName}`,
+      );
     }
     if (config.platform != null) {
       const platforms = Object.keys(config.platform);
       for (const p of platforms) {
         if (p !== "android") {
-          throw new CapacitorConfigError(`unsupported platform: ${p} (currently only android is supported)`);
+          throw new CapacitorConfigError(
+            `지원하지 않는 플랫폼입니다: ${p} (현재 android만 지원)`,
+          );
         }
       }
     }
   }
 
   /**
-   * Execute a Capacitor CLI command via npx
-   */
-  private async _execCap(args: string[]): Promise<string> {
-    return this._exec("npx", ["cap", ...args], this._capPath);
-  }
-
-  /**
-   * Execute capacitor-assets CLI command via npx
-   */
-  private async _execCapAssets(args: string[]): Promise<string> {
-    return this._exec("npx", ["capacitor-assets", ...args], this._capPath);
-  }
-
-  /**
-   * Execute command (with logging)
-   */
-  private async _exec(cmd: string, args: string[], cwd: string): Promise<string> {
-    Capacitor._logger.debug(`executed command: ${cmd} ${args.join(" ")}`);
-
-    const result = await execa(cmd, args, { cwd, reject: false, encoding: "buffer" });
-    const stdout = Capacitor._decodeOutput(result.stdout);
-
-    if (result.exitCode !== 0) {
-      const stderr = Capacitor._decodeOutput(result.stderr);
-      throw new Error(`${cmd} ${args.join(" ")} failed (exit ${result.exitCode}): ${stderr || stdout}`);
-    }
-
-    Capacitor._logger.debug(`execution result: ${stdout}`);
-    return stdout;
-  }
-
-  /**
-   * Decode command output (UTF-8 first, fallback to EUC-KR for Windows CP949)
-   */
-  private static _decodeOutput(bytes: Uint8Array): string {
-    try {
-      return Capacitor._utf8Decoder.decode(bytes);
-    } catch {
-      return Capacitor._fallbackDecoder.decode(bytes);
-    }
-  }
-
-  /**
-   * F10: Acquire lock to prevent concurrent execution
-   */
-  private async _acquireLock(): Promise<void> {
-    const lockPath = path.resolve(this._capPath, Capacitor._LOCK_FILE_NAME);
-    if (await fsx.exists(lockPath)) {
-      const lockContent = await fsx.read(lockPath);
-      throw new Error(
-        `Another Capacitor operation is in progress (PID: ${lockContent}). ` +
-          `If there's an issue, delete the ${lockPath} file.`,
-      );
-    }
-    await fsx.mkdir(this._capPath);
-    await fsx.write(lockPath, String(process.pid));
-  }
-
-  /**
-   * F10: Release lock
-   */
-  private async _releaseLock(): Promise<void> {
-    const lockPath = path.resolve(this._capPath, Capacitor._LOCK_FILE_NAME);
-    await fsx.rm(lockPath);
-  }
-
-  /**
-   * F4: Validate external tools
-   */
-  private async _validateTools(): Promise<void> {
-    // Check Android SDK
-    const sdkPath = await this._findAndroidSdk();
-    if (sdkPath == null) {
-      throw new Error(
-        "Android SDK not found.\n" +
-          "1. Install Android Studio or\n" +
-          "2. Set ANDROID_HOME or ANDROID_SDK_ROOT environment variable.",
-      );
-    }
-
-    // Check Java (only for android platform)
-    if (this._platforms.includes("android")) {
-      const javaPath = await this._findJava21();
-      if (javaPath == null) {
-        Capacitor._logger.warn(
-          "Java 21 not found. Gradle may use embedded JDK or the build may fail.",
-        );
-      }
-    }
-  }
-
-  /**
-   * Initialize Capacitor project
+   * Capacitor 프로젝트 초기화
    *
-   * 1. Create package.json and install dependencies
-   * 2. Create capacitor.config.ts
-   * 3. Add platform (android)
-   * 4. Set up icon
-   * 5. Configure Android native settings
-   * 6. Run cap sync or cap copy
+   * 1. package.json 생성 및 의존성 설치
+   * 2. capacitor.config.ts 생성
+   * 3. 플랫폼 추가 (android)
+   * 4. Android 네이티브 설정 구성
+   * 5. cap sync 또는 cap copy 실행
    */
   async initialize(): Promise<void> {
     await this._acquireLock();
 
     try {
-      // F4: Validate external tools
+      // 외부 도구 검증
       await this._validateTools();
 
-      // 1. Initialize Capacitor project
+      // 1. Capacitor 프로젝트 초기화
       const changed = await this._initCap();
 
-      // 2. Create Capacitor config file
+      // 2. Capacitor 설정 파일 생성
       await this._writeCapConf();
 
-      // 3. Manage platform (F12: idempotent - skip if already exists)
+      // 3. 플랫폼 관리 (멱등성: 이미 존재하면 스킵)
       await this._addPlatforms();
 
-      // 4. Set up icon (F6: error recovery)
+      // 4. 아이콘 처리
       await this._setupIcon();
 
-      // 5. Configure Android native settings
+      // 5. Android 네이티브 설정 구성
       if (this._platforms.includes("android")) {
         await this._configureAndroid();
       }
 
-      // 6. Synchronize web assets
+      // 6. 웹 에셋 동기화
       if (changed) {
         await this._execCap(["sync"]);
       } else {
@@ -235,96 +144,121 @@ export class Capacitor {
     }
   }
 
+  //#region Private - 명령어 실행
+
   /**
-   * Build Android APK/AAB
+   * Capacitor CLI 명령어를 npx로 실행
    */
-  async build(outPath: string): Promise<void> {
-    await this._acquireLock();
+  private async _execCap(args: string[]): Promise<string> {
+    return this._exec("npx", ["cap", ...args], this._capPath);
+  }
 
-    try {
-      const buildType = this._config.debug ? "debug" : "release";
+  /**
+   * 명령어 실행 (execa — Windows .cmd 자동 resolve)
+   */
+  private async _exec(command: string, args: string[], cwd: string): Promise<string> {
+    Capacitor._logger.debug(`명령어 실행: ${command} ${args.join(" ")}`);
+    const { stdout } = await execa(command, args, { cwd });
+    Capacitor._logger.debug(`실행 결과: ${stdout}`);
+    return stdout;
+  }
 
-      for (const platform of this._platforms) {
-        await this._execCap(["copy", platform]);
+  //#endregion
 
-        if (platform === "android") {
-          await this._buildAndroid(outPath, buildType);
-        } else {
-          throw new Error(`unsupported platform: ${platform}`);
-        }
+  //#region Private - 동시 실행 방지
+
+  /**
+   * 동시 실행 방지 잠금 획득
+   */
+  private async _acquireLock(): Promise<void> {
+    const lockPath = path.resolve(this._capPath, Capacitor._LOCK_FILE_NAME);
+    await fsx.mkdir(this._capPath);
+    try {
+      await fs.promises.writeFile(lockPath, String(process.pid), { flag: "wx" });
+    } catch (err: unknown) {
+      if (
+        err instanceof Error &&
+        "code" in err &&
+        (err as NodeJS.ErrnoException).code === "EEXIST"
+      ) {
+        const lockContent = await fsx.read(lockPath);
+        throw new Error(
+          `다른 Capacitor 작업이 진행 중입니다 (PID: ${lockContent}). ` +
+            `문제가 있다면 ${lockPath} 파일을 삭제하세요.`,
+        );
       }
-    } finally {
-      await this._releaseLock();
+      throw err;
     }
   }
 
   /**
-   * Run app on device (connect WebView to development server)
+   * 동시 실행 방지 잠금 해제
    */
-  async runOnDevice(url?: string): Promise<void> {
-    // F11: Validate URL
-    if (url != null) {
-      this._validateUrl(url);
-      await this._updateServerUrl(url);
-    }
+  private async _releaseLock(): Promise<void> {
+    const lockPath = path.resolve(this._capPath, Capacitor._LOCK_FILE_NAME);
+    await fsx.rm(lockPath);
+  }
 
-    for (const platform of this._platforms) {
-      await this._execCap(["copy", platform]);
+  //#endregion
 
-      try {
-        await this._execCap(["run", platform]);
-      } catch (err) {
-        if (platform === "android") {
-          try {
-            await this._exec("adb", ["kill-server"], this._capPath);
-          } catch {
-            // adb kill-server failure is ignored
-          }
-        }
-        throw err;
-      }
-    }
-  }
+  //#region Private - 외부 도구 검증
 
   /**
-   * F11: Validate URL
+   * 외부 도구 검증 (Java 21, Android SDK)
    */
-  private _validateUrl(url: string): void {
-    try {
-      const parsed = new URL(url);
-      if (!["http:", "https:"].includes(parsed.protocol)) {
-        throw new Error(`unsupported protocol: ${parsed.protocol}`);
-      }
-    } catch (err) {
-      if (err instanceof TypeError) {
-        throw new Error(`invalid URL: ${url}`);
+  private async _validateTools(): Promise<void> {
+    // Android SDK 확인
+    const sdkPath = await this._findAndroidSdk();
+    if (sdkPath == null) {
+      throw new Error(
+        "Android SDK를 찾을 수 없습니다.\n" +
+          "1. Android Studio를 설치하거나\n" +
+          "2. ANDROID_HOME 또는 ANDROID_SDK_ROOT 환경 변수를 설정하세요.",
+      );
+    }
+
+    // Java 확인 (android 플랫폼인 경우에만)
+    if (this._platforms.includes("android")) {
+      const javaPath = await this._findJava21();
+      if (javaPath == null) {
+        Capacitor._logger.warn(
+          "Java 21을 찾을 수 없습니다. Gradle이 내장 JDK를 사용하거나 빌드가 실패할 수 있습니다.",
+        );
       }
-      throw err;
     }
   }
 
-  //#region Private - Initialization
+  //#endregion
+
+  //#region Private - 초기화
 
   /**
-   * Basic Capacitor project initialization (package.json, pnpm install, cap init)
+   * Capacitor 프로젝트 기본 초기화 (package.json, npm install, cap init)
    */
   private async _initCap(): Promise<boolean> {
-    const depChanged = await this._setupNpmConf();
+    const { depChanged, workspacePlugins } = await this._setupNpmConf();
     const nodeModulesExists = await fsx.exists(path.resolve(this._capPath, "node_modules"));
 
-    if (!depChanged && nodeModulesExists) return false;
+    if (!depChanged && nodeModulesExists) {
+      // 의존성 미변경이어도 workspace 플러그인 symlink는 항상 갱신
+      await this._linkWorkspacePlugins(workspacePlugins);
+      return false;
+    }
 
-    // pnpm install
+    // npm install
     const installResult = await this._exec("npm", ["install"], this._capPath);
-    Capacitor._logger.debug(`npm install completed: ${installResult}`);
+    Capacitor._logger.debug(`npm install 완료: ${installResult}`);
 
-    // F12: cap init idempotency - execute only when capacitor.config.ts does not exist
+    // workspace 플러그인 symlink
+    await this._linkWorkspacePlugins(workspacePlugins);
+
+    // 멱등성: capacitor.config.ts가 없을 때만 cap init 실행
     const configPath = path.resolve(this._capPath, "capacitor.config.ts");
     if (!(await fsx.exists(configPath))) {
       await this._execCap(["init", this._config.appId, this._config.appId]);
     }
 
-    // Create default www/index.html
+    // 기본 www/index.html 생성
     const wwwPath = path.resolve(this._capPath, "www");
     await fsx.mkdir(wwwPath);
     await fsx.write(
@@ -336,14 +270,14 @@ export class Capacitor {
   }
 
   /**
-   * Configure package.json
+   * package.json 설정
    */
-  private async _setupNpmConf(): Promise<boolean> {
-    const projNpmConfigPath = path.resolve(this._pkgPath, "../../package.json");
+  private async _setupNpmConf(): Promise<{ depChanged: boolean; workspacePlugins: string[] }> {
+    const projNpmConfigPath = path.resolve(this._findWorkspaceRoot(), "package.json");
 
-    // F3: Check if file exists
+    // 루트 package.json 존재 확인
     if (!(await fsx.exists(projNpmConfigPath))) {
-      throw new Error(`root package.json not found: ${projNpmConfigPath}`);
+      throw new Error(`루트 package.json을 찾을 수 없습니다: ${projNpmConfigPath}`);
     }
 
     const projNpmConfig = await fsx.readJson<NpmConfig>(projNpmConfigPath);
@@ -360,7 +294,7 @@ export class Capacitor {
       capNpmConf.volta = projNpmConfig.volta;
     }
 
-    // Default dependencies
+    // 기본 의존성
     capNpmConf.dependencies = capNpmConf.dependencies ?? {};
     capNpmConf.dependencies["@capacitor/core"] = "^7.0.0";
     capNpmConf.dependencies["@capacitor/app"] = "^7.0.0";
@@ -372,7 +306,7 @@ export class Capacitor {
     capNpmConf.devDependencies["@capacitor/cli"] = "^7.0.0";
     capNpmConf.devDependencies["@capacitor/assets"] = "^3.0.0";
 
-    // Configure plugin packages
+    // 플러그인 패키지 설정
     const mainDeps = {
       ...this._npmConfig.dependencies,
       ...this._npmConfig.devDependencies,
@@ -388,52 +322,59 @@ export class Capacitor {
         ),
     );
 
-    // Remove unused plugins
+    // 사용하지 않는 플러그인 제거
     for (const prevPlugin of prevPlugins) {
       if (!usePlugins.includes(prevPlugin)) {
         delete capNpmConf.dependencies[prevPlugin];
-        Capacitor._logger.debug(`plugin removed: ${prevPlugin}`);
+        Capacitor._logger.debug(`플러그인 제거: ${prevPlugin}`);
       }
     }
 
-    // Add new plugins
+    // 새 플러그인 추가 (workspace:* 플러그인은 분리)
+    const workspacePlugins: string[] = [];
     for (const plugin of usePlugins) {
-      if (!(plugin in capNpmConf.dependencies)) {
-        const version = mainDeps[plugin] ?? "*";
+      const version = mainDeps[plugin] ?? "*";
+      if (typeof version === "string" && version.startsWith("workspace:")) {
+        // workspace 플러그인은 package.json에 추가하지 않고 symlink로 처리
+        workspacePlugins.push(plugin);
+        // 이전에 추가되어 있었으면 제거
+        delete capNpmConf.dependencies[plugin];
+        Capacitor._logger.debug(`workspace 플러그인 (symlink 예정): ${plugin}`);
+      } else if (!(plugin in capNpmConf.dependencies)) {
         capNpmConf.dependencies[plugin] = version;
-        Capacitor._logger.debug(`plugin added: ${plugin}@${version}`);
+        Capacitor._logger.debug(`플러그인 추가: ${plugin}@${version}`);
       }
     }
 
-    // Add exclude packages
+    // exclude 패키지 추가
     for (const excludePkg of this._exclude) {
       if (!(excludePkg in capNpmConf.dependencies)) {
         const version = mainDeps[excludePkg] ?? "*";
         capNpmConf.dependencies[excludePkg] = version;
-        Capacitor._logger.debug(`exclude package added: ${excludePkg}@${version}`);
+        Capacitor._logger.debug(`exclude 패키지 추가: ${excludePkg}@${version}`);
       }
     }
 
-    // Save
+    // 저장
     await fsx.mkdir(this._capPath);
     await fsx.writeJson(capNpmConfPath, capNpmConf, { space: 2 });
 
-    // Check if dependencies changed
+    // 의존성 변경 여부 확인
     const isChanged =
       orgCapNpmConf.volta !== capNpmConf.volta ||
       JSON.stringify(orgCapNpmConf.dependencies) !== JSON.stringify(capNpmConf.dependencies) ||
       JSON.stringify(orgCapNpmConf.devDependencies) !== JSON.stringify(capNpmConf.devDependencies);
 
-    return isChanged;
+    return { depChanged: isChanged, workspacePlugins };
   }
 
   /**
-   * Create capacitor.config.ts
+   * capacitor.config.ts 생성
    */
   private async _writeCapConf(): Promise<void> {
     const confPath = path.resolve(this._capPath, "capacitor.config.ts");
 
-    // Create plugin options
+    // 플러그인 옵션 생성
     const pluginOptions: Record<string, Record<string, unknown>> = {};
     for (const [pluginName, options] of Object.entries(this._config.plugins ?? {})) {
       if (options !== true) {
@@ -467,13 +408,13 @@ export default config;
   }
 
   /**
-   * Add platform (F12: ensure idempotency)
+   * 플랫폼 추가 (멱등성: 이미 존재하면 스킵)
    */
   private async _addPlatforms(): Promise<void> {
     for (const platform of this._platforms) {
       const platformPath = path.resolve(this._capPath, platform);
       if (await fsx.exists(platformPath)) {
-        Capacitor._logger.debug(`platform already exists: ${platform}`);
+        Capacitor._logger.debug(`플랫폼이 이미 존재합니다: ${platform}`);
         continue;
       }
 
@@ -482,77 +423,82 @@ export default config;
   }
 
   /**
-   * Set up icon (F6: error recovery)
+   * 앱 아이콘 처리 (소스 이미지 → 멀티 해상도 아이콘 + 스플래시)
    */
   private async _setupIcon(): Promise<void> {
-    const assetsDirPath = path.resolve(this._capPath, "assets");
+    if (this._config.icon == null) return;
 
-    if (this._config.icon != null) {
-      const iconSource = path.resolve(this._pkgPath, this._config.icon);
+    const iconPath = path.resolve(this._pkgPath, this._config.icon);
 
-      // F6: Check if source icon exists
-      if (!(await fsx.exists(iconSource))) {
-        Capacitor._logger.warn(
-          `icon file not found: ${iconSource}. Using default icon.`,
-        );
-        return;
-      }
+    if (!(await fsx.exists(iconPath))) {
+      Capacitor._logger.warn(`아이콘 파일을 찾을 수 없습니다: ${iconPath}`);
+      return;
+    }
 
-      try {
-        await fsx.mkdir(assetsDirPath);
-
-        // Create icon
-        const logoPath = path.resolve(assetsDirPath, "logo.png");
-
-        const logoSize = Math.floor(1024 * 0.6);
-        const padding = Math.floor((1024 - logoSize) / 2);
-
-        // F6: Handle sharp errors
-        await sharp(iconSource)
-          .resize(logoSize, logoSize, {
-            fit: "contain",
-            background: { r: 0, g: 0, b: 0, alpha: 0 },
-          })
-          .extend({
-            top: padding,
-            bottom: padding,
-            left: padding,
-            right: padding,
-            background: { r: 0, g: 0, b: 0, alpha: 0 },
-          })
-          .toFile(logoPath);
-
-        await this._execCapAssets([
+    try {
+      const sharp = (await import("sharp")).default;
+
+      // 소스 이미지를 리사이즈 (60% of 1024 = ~614px)
+      const canvasSize = 1024;
+      const contentSize = Math.round(canvasSize * 0.6);
+
+      const resizedBuffer = await sharp(iconPath)
+        .resize(contentSize, contentSize, { fit: "inside" })
+        .png()
+        .toBuffer();
+
+      // 1024x1024 투명 캔버스에 합성
+      const assetsDir = path.resolve(this._capPath, "assets");
+      await fsx.mkdir(assetsDir);
+      const logoPath = path.resolve(assetsDir, "logo.png");
+
+      await sharp({
+        create: {
+          width: canvasSize,
+          height: canvasSize,
+          channels: 4 as const,
+          background: { r: 0, g: 0, b: 0, alpha: 0 },
+        },
+      })
+        .composite([{ input: resizedBuffer, gravity: "center" }])
+        .png()
+        .toFile(logoPath);
+
+      // capacitor-assets로 모든 해상도 아이콘/스플래시 생성
+      await this._exec(
+        "npx",
+        [
+          "capacitor-assets",
           "generate",
           "--iconBackgroundColor",
-          "#ffffff",
+          "transparent",
           "--splashBackgroundColor",
-          "#ffffff",
-        ]);
-      } catch (err) {
-        Capacitor._logger.warn(
-          `icon generation failed: ${err instanceof Error ? err.message : err}. Using default icon.`,
-        );
-        // F6: Continue even if it fails (use default icon)
-      }
-    } else {
-      await fsx.rm(assetsDirPath);
+          "transparent",
+          "--logoSplashScale",
+          "0.6",
+        ],
+        this._capPath,
+      );
+    } catch (err) {
+      Capacitor._logger.warn(
+        `아이콘 생성에 실패했습니다: ${err instanceof Error ? err.message : err}`,
+      );
     }
   }
 
   //#endregion
 
-  //#region Private - Android Configuration
+  //#region Private - Android 설정
 
   /**
-   * Configure Android native settings
+   * Android 네이티브 설정 구성
    */
   private async _configureAndroid(): Promise<void> {
     const androidPath = path.resolve(this._capPath, "android");
 
-    // F3: Check if Android directory exists
+    // Android 디렉토리 존재 확인
     if (!(await fsx.exists(androidPath))) {
-      throw new Error(`Android project directory not found: ${androidPath}`);
+      throw new Error(`Android 프로젝트 디렉토리를 찾을 수 없습니다: ${androidPath}`);
     }
 
     await this._configureAndroidJavaHomePath(androidPath);
@@ -562,14 +508,13 @@ export default config;
   }
 
   /**
-   * Set up JAVA_HOME path (gradle.properties)
+   * JAVA_HOME 경로 설정 (gradle.properties)
    */
   private async _configureAndroidJavaHomePath(androidPath: string): Promise<void> {
     const gradlePropsPath = path.resolve(androidPath, "gradle.properties");
 
-    // F3: Check if file exists
     if (!(await fsx.exists(gradlePropsPath))) {
-      Capacitor._logger.warn(`gradle.properties file not found: ${gradlePropsPath}`);
+      Capacitor._logger.warn(`gradle.properties 파일을 찾을 수 없습니다: ${gradlePropsPath}`);
       return;
     }
 
@@ -577,7 +522,7 @@ export default config;
 
     const java21Path = await this._findJava21();
     if (java21Path != null && !content.includes("org.gradle.java.home")) {
-      // F9: Improved Windows path escaping
+      // Windows 경로 이스케이프
       const escapedPath = java21Path.replace(/\\/g, "\\\\");
       content += `\norg.gradle.java.home=${escapedPath}\n`;
       await fsx.write(gradlePropsPath, content);
@@ -585,7 +530,7 @@ export default config;
   }
 
   /**
-   * Auto-detect Java 21 path
+   * Java 21 경로 자동 탐색
    */
   private async _findJava21(): Promise<string | undefined> {
     const patterns = [
@@ -608,31 +553,31 @@ export default config;
   }
 
   /**
-   * Set up Android SDK path (local.properties)
+   * Android SDK 경로 설정 (local.properties)
    */
   private async _configureAndroidSdkPath(androidPath: string): Promise<void> {
     const localPropsPath = path.resolve(androidPath, "local.properties");
 
     const sdkPath = await this._findAndroidSdk();
     if (sdkPath != null) {
-      // F9: Always use forward slash (Gradle compatible)
+      // Gradle 호환: 항상 forward slash 사용
       await fsx.write(localPropsPath, `sdk.dir=${sdkPath.replace(/\\/g, "/")}\n`);
     } else {
       throw new Error(
-        "Android SDK not found.\n" +
-          "1. Install Android Studio or\n" +
-          "2. Set ANDROID_HOME or ANDROID_SDK_ROOT environment variable.",
+        "Android SDK를 찾을 수 없습니다.\n" +
+          "1. Android Studio를 설치하거나\n" +
+          "2. ANDROID_HOME 또는 ANDROID_SDK_ROOT 환경 변수를 설정하세요.",
       );
     }
   }
 
   /**
-   * Search for Android SDK path
+   * Android SDK 경로 탐색
    */
   private async _findAndroidSdk(): Promise<string | undefined> {
-    const fromEnv = (env["ANDROID_HOME"] ?? env["ANDROID_SDK_ROOT"]) as string | undefined;
-    if (fromEnv != null && (await fsx.exists(fromEnv))) {
-      return fromEnv;
+    const androidHome = (env["ANDROID_HOME"] as string | undefined) ?? (env["ANDROID_SDK_ROOT"] as string | undefined);
+    if (androidHome != null && (await fsx.exists(androidHome))) {
+      return androidHome;
     }
 
     const candidates = [
@@ -652,24 +597,26 @@ export default config;
   }
 
   /**
-   * Modify AndroidManifest.xml (F3: add error handling)
+   * AndroidManifest.xml 설정
+   *
+   * 주의: Capacitor가 생성하는 초기 XML 포맷에 의존하는 정규식 기반 수정.
+   * XML 구조가 변경되면 정규식이 실패할 수 있음.
    */
   private async _configureAndroidManifest(androidPath: string): Promise<void> {
     const manifestPath = path.resolve(androidPath, "app/src/main/AndroidManifest.xml");
 
-    // F3: Check if file exists
     if (!(await fsx.exists(manifestPath))) {
-      throw new Error(`AndroidManifest.xml file not found: ${manifestPath}`);
+      throw new Error(`AndroidManifest.xml 파일을 찾을 수 없습니다: ${manifestPath}`);
     }
 
     let content = await fsx.read(manifestPath);
 
-    // Configure usesCleartextTraffic
+    // usesCleartextTraffic 설정
     if (!content.includes("android:usesCleartextTraffic")) {
       content = content.replace("<application", '<application android:usesCleartextTraffic="true"');
     }
 
-    // Configure additional permissions
+    // 추가 권한 설정
     const permissions = this._config.platform?.android?.permissions ?? [];
     for (const perm of permissions) {
       const permTag = `<uses-permission android:name="android.permission.${perm.name}"`;
@@ -690,7 +637,7 @@ export default config;
       }
     }
 
-    // Configure additional application settings
+    // 추가 application 속성 설정
     const appConfig = this._config.platform?.android?.config;
     if (appConfig) {
       for (const [key, value] of Object.entries(appConfig)) {
@@ -701,7 +648,7 @@ export default config;
       }
     }
 
-    // Configure intentFilters
+    // intentFilters 설정
     const intentFilters = this._config.platform?.android?.intentFilters ?? [];
     for (const filter of intentFilters) {
       const filterKey = filter.action ?? filter.category ?? "";
@@ -725,19 +672,18 @@ export default config;
   }
 
   /**
-   * Modify build.gradle (F3: add error handling)
+   * build.gradle 수정 (서명 설정 제외)
    */
   private async _configureAndroidBuildGradle(androidPath: string): Promise<void> {
     const buildGradlePath = path.resolve(androidPath, "app/build.gradle");
 
-    // F3: Check if file exists
     if (!(await fsx.exists(buildGradlePath))) {
-      throw new Error(`build.gradle file not found: ${buildGradlePath}`);
+      throw new Error(`build.gradle 파일을 찾을 수 없습니다: ${buildGradlePath}`);
     }
 
     let content = await fsx.read(buildGradlePath);
 
-    // Configure versionName and versionCode
+    // versionName, versionCode 설정
     const version = this._npmConfig.version;
     const cleanVersion = version.replace(/-.*$/, "");
     const versionParts = cleanVersion.split(".");
@@ -749,7 +695,7 @@ export default config;
     content = content.replace(/versionCode \d+/, `versionCode ${versionCode}`);
     content = content.replace(/versionName "[^"]+"/, `versionName "${version}"`);
 
-    // Configure SDK version
+    // SDK 버전 설정
     if (this._config.platform?.android?.sdkVersion != null) {
       const sdkVersion = this._config.platform.android.sdkVersion;
       content = content.replace(/minSdkVersion .+/, `minSdkVersion ${sdkVersion}`);
@@ -762,164 +708,272 @@ export default config;
       );
     }
 
-    // Configure signing
-    const keystorePath = path.resolve(this._capPath, Capacitor._ANDROID_KEYSTORE_FILE_NAME);
-    const signConfig = this._config.platform?.android?.sign;
-    if (signConfig) {
-      const keystoreSource = path.resolve(this._pkgPath, signConfig.keystore);
-      // F3: Check if keystore file exists
-      if (!(await fsx.exists(keystoreSource))) {
-        throw new Error(`keystore file not found: ${keystoreSource}`);
-      }
-      await fsx.copy(keystoreSource, keystorePath);
+    await fsx.write(buildGradlePath, content);
+  }
+
+  //#endregion
 
-      // F9: Convert relative path to forward slash
-      const keystoreRelativePath = path
-        .relative(path.dirname(buildGradlePath), keystorePath)
-        .replace(/\\/g, "/");
-      const keystoreType = signConfig.keystoreType ?? "jks";
+  //#region Public — 기기 실행
 
-      if (!content.includes("signingConfigs")) {
-        const signingConfigsBlock = `
-    signingConfigs {
-        release {
-            storeFile file("${keystoreRelativePath}")
-            storePassword '${Capacitor._escapeGroovyString(signConfig.storePassword)}'
-            keyAlias '${Capacitor._escapeGroovyString(signConfig.alias)}'
-            keyPassword '${Capacitor._escapeGroovyString(signConfig.password)}'
-            storeType "${keystoreType}"
+  /**
+   * 기기에서 앱을 실행한다 (개발 모드).
+   *
+   * 1. capacitor.config.ts에 server.url 설정 (Hot Reload용)
+   * 2. cap copy — 웹 에셋 동기화
+   * 3. cap run — 기기에서 앱 실행 (실패 시 adb kill-server 후 1회 재시도)
+   */
+  async run(url: string): Promise<void> {
+    await this._updateServerUrl(url);
+
+    for (const platform of this._platforms) {
+      await this._execCap(["copy", platform]);
+
+      try {
+        await this._execCap(["run", platform]);
+      } catch (err) {
+        if (platform === "android") {
+          Capacitor._logger.warn("cap run 실패. adb kill-server 후 재시도합니다.");
+          try {
+            await this._exec("adb", ["kill-server"], this._capPath);
+          } catch {
+            // adb kill-server 실패는 무시
+          }
+          await this._execCap(["run", platform]);
+        } else {
+          throw err;
         }
-    }
-`;
-        content = content.replace(/(android\s*\{)/, (match) => `${match}${signingConfigsBlock}`);
       }
+    }
+  }
 
-      if (!content.includes("signingConfig signingConfigs.release")) {
-        content = content.replace(
-          /(buildTypes\s*\{[\s\S]*?release\s*\{)/,
-          `$1\n            signingConfig signingConfigs.release`,
-        );
-      }
-    } else {
-      await fsx.rm(keystorePath);
+  //#endregion
+
+  //#region Private — 기기 실행
+
+  /**
+   * capacitor.config.ts의 server.url을 업데이트한다.
+   * WebView가 이 URL에서 웹 에셋을 로드하여 Hot Reload가 동작한다.
+   */
+  private async _updateServerUrl(url: string): Promise<void> {
+    const configPath = path.resolve(this._capPath, "capacitor.config.ts");
+    let content = await fsx.read(configPath);
+
+    if (content.includes("url:")) {
+      content = content.replace(/url:\s*"[^"]*"/, `url: "${url}"`);
+    } else if (content.includes("server:")) {
+      content = content.replace(/server:\s*\{/, `server: {\n    url: "${url}",`);
     }
 
-    await fsx.write(buildGradlePath, content);
+    await fsx.write(configPath, content);
   }
 
+  //#endregion
+
+  //#region Public — 빌드
+
   /**
-   * Escape single quotes in Groovy string (for use in single-quoted strings)
-   * Groovy: 'string with \'single quote\' inside'
+   * Capacitor 프로덕션 빌드 (APK/AAB 생성)
+   *
+   * 1. cap copy (웹 에셋 → 네이티브 프로젝트 동기화)
+   * 2. 서명 설정 (sign 설정 있을 때)
+   * 3. Gradle 빌드 (APK 또는 AAB)
+   * 4. 빌드 산출물 복사
    */
-  private static _escapeGroovyString(value: string): string {
-    return value.replace(/'/g, "\\'");
+  async build(outPath: string): Promise<void> {
+    // 1. 웹 에셋 동기화
+    await this._execCap(["copy"]);
+
+    // 2. 빌드 타입 결정
+    const isDebug = this._config.debug === true;
+    const isBundle = this._config.platform?.android?.bundle === true;
+    const buildType = isDebug ? "debug" : "release";
+
+    // 3. 서명 설정
+    const signConfig = this._config.platform?.android?.sign;
+    if (!isDebug && signConfig != null) {
+      await this._configureSigningConfig(
+        path.resolve(this._capPath, "android"),
+        signConfig,
+      );
+    } else if (!isDebug) {
+      Capacitor._logger.warn("서명 설정이 없어 unsigned 빌드가 생성됩니다.");
+    }
+
+    // 4. Gradle 빌드
+    await this._buildAndroid(buildType, isBundle);
+
+    // 5. 빌드 산출물 복사
+    await this._copyBuildOutput(outPath, buildType, isBundle);
   }
 
   //#endregion
 
-  //#region Private - Build
+  //#region Private — 빌드
 
   /**
-   * Build Android
+   * 서명 설정을 build.gradle에 추가하고 keystore 파일을 복사
    */
-  private async _buildAndroid(outPath: string, buildType: string): Promise<void> {
-    const androidPath = path.resolve(this._capPath, "android");
-    const targetOutPath = path.resolve(outPath, "android");
+  private async _configureSigningConfig(
+    androidPath: string,
+    sign: import("../sd-config.types.js").SdCapacitorSignConfig,
+  ): Promise<void> {
+    // keystore 파일 확인 및 복사
+    const keystoreSrc = path.resolve(this._pkgPath, sign.keystore);
+    if (!(await fsx.exists(keystoreSrc))) {
+      throw new Error(`keystore 파일을 찾을 수 없습니다: ${keystoreSrc}`);
+    }
+
+    const keystoreDest = path.resolve(androidPath, "app", "android.keystore");
+    await fsx.copy(keystoreSrc, keystoreDest);
 
-    const isBundle = this._config.platform?.android?.bundle;
-    const gradleTask =
-      buildType === "release" ? (isBundle ? "bundleRelease" : "assembleRelease") : "assembleDebug";
+    // build.gradle에 signingConfigs 추가
+    const buildGradlePath = path.resolve(androidPath, "app/build.gradle");
+    let content = await fsx.read(buildGradlePath);
+
+    // 이미 signingConfigs가 있으면 스킵
+    if (content.includes("signingConfigs")) return;
+
+    const storeType = sign.keystoreType ?? "jks";
+    const escapedStorePassword = sign.storePassword.replace(/'/g, "\\'");
+    const escapedKeyPassword = sign.password.replace(/'/g, "\\'");
+
+    const signingBlock = `    signingConfigs {
+        release {
+            storeFile file("android.keystore")
+            storePassword '${escapedStorePassword}'
+            keyAlias '${sign.alias}'
+            keyPassword '${escapedKeyPassword}'
+            storeType "${storeType}"
+        }
+    }
+`;
+
+    // signingConfigs 블록을 buildTypes 앞에 삽입
+    content = content.replace(/(\s*buildTypes\s*\{)/, `${signingBlock}$1`);
+
+    // buildTypes.release에 signingConfig 추가
+    content = content.replace(
+      /(buildTypes\s*\{[\s\S]*?release\s*\{)/,
+      "$1\n            signingConfig signingConfigs.release",
+    );
 
-    // Execute Gradle build (cross-platform)
-    // F9: Run via cmd.exe on Windows (because shell: false)
-    if (process.platform === "win32") {
-      await this._exec("cmd", ["/c", "gradlew.bat", gradleTask, "--no-daemon"], androidPath);
+    await fsx.write(buildGradlePath, content);
+  }
+
+  /**
+   * Gradle 빌드 실행 (cross-platform)
+   */
+  private async _buildAndroid(buildType: string, isBundle: boolean): Promise<void> {
+    let gradleTask: string;
+    if (buildType === "debug") {
+      gradleTask = "assembleDebug";
+    } else if (isBundle) {
+      gradleTask = "bundleRelease";
     } else {
-      await this._exec("sh", ["./gradlew", gradleTask, "--no-daemon"], androidPath);
+      gradleTask = "assembleRelease";
     }
 
-    // Copy build output
-    await this._copyAndroidBuildOutput(androidPath, targetOutPath, buildType);
+    const androidPath = path.resolve(this._capPath, "android");
+    const isWindows = process.platform === "win32";
+    const gradlew = isWindows
+      ? path.resolve(androidPath, "gradlew.bat")
+      : path.resolve(androidPath, "gradlew");
+
+    await this._exec(gradlew, [gradleTask, "--no-daemon"], androidPath);
   }
 
   /**
-   * Copy Android build output
+   * 빌드 산출물을 출력 경로에 복사
    */
-  private async _copyAndroidBuildOutput(
-    androidPath: string,
-    targetOutPath: string,
+  private async _copyBuildOutput(
+    outPath: string,
     buildType: string,
+    isBundle: boolean,
   ): Promise<void> {
-    const isBundle = this._config.platform?.android?.bundle;
-    const isSigned = Boolean(this._config.platform?.android?.sign);
-
     const ext = isBundle ? "aab" : "apk";
     const outputType = isBundle ? "bundle" : "apk";
-    const fileName = isSigned ? `app-${buildType}.${ext}` : `app-${buildType}-unsigned.${ext}`;
-
-    const sourcePath = path.resolve(
-      androidPath,
-      "app/build/outputs",
+    const androidBuildPath = path.resolve(
+      this._capPath,
+      "android/app/build/outputs",
       outputType,
       buildType,
-      fileName,
     );
 
-    const actualPath = (await fsx.exists(sourcePath))
-      ? sourcePath
-      : path.resolve(
-          androidPath,
-          "app/build/outputs",
-          outputType,
-          buildType,
-          `app-${buildType}.${ext}`,
-        );
-
-    if (!(await fsx.exists(actualPath))) {
-      Capacitor._logger.warn(`build output not found: ${actualPath}`);
-      return;
+    // 빌드 산출물 찾기
+    const candidates = await fsx.glob(path.resolve(androidBuildPath, `app-*.${ext}`));
+    if (candidates.length === 0) {
+      throw new Error(`빌드 산출물을 찾을 수 없습니다: ${androidBuildPath}`);
     }
+    const builtFile = candidates[0];
+    const isUnsigned = builtFile.includes("unsigned");
 
-    const outputFileName = `${this._config.appName}${isSigned ? "" : "-unsigned"}-latest.${ext}`;
+    // 출력 디렉토리 생성
+    const androidOutPath = path.resolve(outPath, "android");
+    const updatesPath = path.resolve(androidOutPath, "updates");
+    await fsx.mkdir(androidOutPath);
+    await fsx.mkdir(updatesPath);
 
-    await fsx.mkdir(targetOutPath);
-    await fsx.copy(actualPath, path.resolve(targetOutPath, outputFileName));
+    // latest 파일명 결정
+    const unsignedSuffix = isUnsigned ? "-unsigned" : "";
+    const latestName = `${this._config.appName}${unsignedSuffix}-latest.${ext}`;
+    const versionedName = `${this._npmConfig.version}.${ext}`;
 
-    // Save per-version
-    const updatesPath = path.resolve(targetOutPath, "updates");
-    await fsx.mkdir(updatesPath);
-    await fsx.copy(actualPath, path.resolve(updatesPath, `${this._npmConfig.version}.${ext}`));
+    // 복사
+    await fsx.copy(builtFile, path.resolve(androidOutPath, latestName));
+    await fsx.copy(builtFile, path.resolve(updatesPath, versionedName));
   }
 
   //#endregion
 
-  //#region Private - Device Execution
+  //#region Private - 유틸리티
 
   /**
-   * Update server.url in capacitor.config.ts
+   * workspace:* 플러그인을 .capacitor/node_modules/에 symlink로 연결한다.
+   * cap sync는 플러그인의 android/ 네이티브 코드만 필요하므로 JS 의존성 resolve 불필요.
    */
-  private async _updateServerUrl(url: string): Promise<void> {
-    const configPath = path.resolve(this._capPath, "capacitor.config.ts");
+  private async _linkWorkspacePlugins(plugins: string[]): Promise<void> {
+    if (plugins.length === 0) return;
 
-    if (!(await fsx.exists(configPath))) return;
+    const require = createRequire(path.resolve(this._pkgPath, "package.json"));
 
-    let content = await fsx.read(configPath);
+    for (const plugin of plugins) {
+      const pluginPkgJsonPath = require.resolve(`${plugin}/package.json`);
+      const pluginDir = path.dirname(pluginPkgJsonPath);
 
-    if (content.includes("url:")) {
-      content = content.replace(/url:\s*"[^"]*"/, `url: "${url}"`);
-    } else if (content.includes("server:")) {
-      content = content.replace(/server:\s*\{/, `server: {\n    url: "${url}",`);
-    }
+      const linkPath = path.resolve(this._capPath, "node_modules", ...plugin.split("/"));
 
-    await fsx.write(configPath, content);
-  }
+      // scope 디렉토리 생성 (예: @simplysm/)
+      await fsx.mkdir(path.dirname(linkPath));
 
-  //#endregion
+      // 기존 symlink가 있으면 삭제
+      if (await fsx.exists(linkPath)) {
+        await fsx.rm(linkPath);
+      }
+
+      await symlink(pluginDir, linkPath, "junction");
+      Capacitor._logger.debug(`workspace 플러그인 symlink: ${plugin} → ${pluginDir}`);
+    }
+  }
 
-  //#region Private - Utilities
+  /**
+   * pnpm-workspace.yaml이 있는 워크스페이스 루트 디렉토리를 찾는다.
+   */
+  private _findWorkspaceRoot(): string {
+    let dir = this._pkgPath;
+    while (true) {
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        throw new Error(`워크스페이스 루트를 찾을 수 없습니다: ${this._pkgPath}`);
+      }
+      if (existsSync(path.join(parent, "pnpm-workspace.yaml"))) {
+        return parent;
+      }
+      dir = parent;
+    }
+  }
 
   /**
-   * Convert string to PascalCase
+   * 문자열을 PascalCase로 변환
    */
   private _toPascalCase(str: string): string {
     return str