@simplysm/sd-cli 14.0.10 → 14.0.12

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

@@ -0,0 +1,65 @@
+import { consola } from "consola";
+import { pathx } from "@simplysm/core-node";
+import { SdError } from "@simplysm/core-common";
+import { loadSdConfig } from "../utils/sd-config";
+import { Capacitor } from "../capacitor/capacitor";
+import { Electron } from "../electron/electron";
+
+const logger = consola.withTag("sd:cli:device");
+
+export interface DeviceOptions {
+  package: string;
+  url?: string;
+  options: string[];
+}
+
+/**
+ * 네이티브 앱을 디바이스/데스크톱에서 실행한다.
+ *
+ * - Electron 설정이 Capacitor보다 우선한다.
+ * - --url이 제공되지 않으면 sd.config.ts의 서버 포트로 자동 생성한다.
+ */
+export async function runDevice(options: DeviceOptions): Promise<void> {
+  const cwd = process.cwd();
+  const sdConfig = await loadSdConfig({ cwd, dev: true, options: options.options });
+
+  const pkgConfig = sdConfig.packages[options.package];
+  if (pkgConfig == null) {
+    throw new SdError(`패키지를 찾을 수 없습니다: ${options.package}`);
+  }
+  if (pkgConfig.target !== "client") {
+    throw new SdError(`client 패키지만 device 실행이 가능합니다: ${options.package} (target: ${pkgConfig.target})`);
+  }
+
+  const clientConfig = pkgConfig;
+  const pkgDir = pathx.posixResolve(cwd, "packages", options.package);
+
+  // 서버 URL 결정
+  let serverUrl = options.url;
+  if (serverUrl == null) {
+    if (typeof clientConfig.server === "number") {
+      serverUrl = `http://localhost:${clientConfig.server}`;
+    } else {
+      throw new SdError(
+        `--url 옵션이 필요합니다. server가 패키지명으로 설정되어 있습니다: ${clientConfig.server}`,
+      );
+    }
+  }
+
+  // Electron이 Capacitor보다 우선
+  if (clientConfig.electron != null) {
+    logger.start(`${options.package} (electron) 실행 중...`);
+    const electron = await Electron.create(pkgDir, clientConfig.electron, clientConfig.exclude);
+    await electron.run(serverUrl);
+    logger.success(`${options.package} (electron) 실행 완료`);
+  } else if (clientConfig.capacitor != null) {
+    logger.start(`${options.package} (capacitor) 실행 중...`);
+    const cap = await Capacitor.create(pkgDir, clientConfig.capacitor, clientConfig.exclude);
+    await cap.run(serverUrl);
+    logger.success(`${options.package} (capacitor) 실행 완료`);
+  } else {
+    throw new SdError(
+      `${options.package}에 capacitor 또는 electron 설정이 없습니다.`,
+    );
+  }
+}

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 실패 시 경고만 출력 (배포 롤백 불가)

package/src/commands/replace-deps.ts

@@ -3,15 +3,15 @@ import { loadSdConfig } from "../utils/sd-config";
 import { setupReplaceDeps } from "../utils/replace-deps";
 
 /**
- * replace-deps command options
+ * replace-deps 명령어 옵션
  */
 export interface ReplaceDepsOptions {
-  /** Additional options to pass to sd.config.ts */
+  /** sd.config.ts에 전달할 추가 옵션 */
   options: string[];
 }
 
 /**
- * Replace node_modules packages with symlinks to local source based on replaceDeps config in sd.config.ts.
+ * sd.config.ts의 replaceDeps 설정에 따라 node_modules 패키지를 로컬 소스 심볼릭 링크로 교체한다.
  */
 export async function runReplaceDeps(opts: ReplaceDepsOptions): Promise<void> {
   const cwd = process.cwd();

package/src/commands/typecheck.ts

@@ -2,7 +2,6 @@ import ts from "typescript";
 import { err as errNs } from "@simplysm/core-common";
 import { pathx } from "@simplysm/core-node";
 import { consola } from "consola";
-import type { SdConfig } from "../sd-config.types";
 import { loadSdConfig } from "../utils/sd-config";
 import { deserializeDiagnostic } from "../utils/typecheck-serialization";
 import { createBuildEngine } from "../engines/index";
@@ -35,14 +34,14 @@ export interface TypecheckResult {
   errorCount: number;
   warningCount: number;
   formattedOutput: string;
-  /** Lint result (present when TypecheckOptions.lint is true) */
+  /** lint 결과 (TypecheckOptions.lint가 true일 때 존재) */
   lint?: {
     success: boolean;
     errorCount: number;
     warningCount: number;
     formattedOutput: string;
   };
-  /** Paths of scripts packages that were skipped (for separate lint) */
+  /** 건너뛴 scripts 패키지 경로 (별도 lint용) */
   scriptsPackagePaths?: string[];
 }
 
@@ -75,7 +74,8 @@ function extractTargetPackageNames(targets: string[]): Set<string> {
  *
  * sd.config.ts의 각 패키지에 대해:
  * - 라이브러리/서버 패키지 → BuildEngine.run({js:false, dts:false})
- * - 스크립트/클라이언트 패키지 → 제외
+ * - client 패키지 → browser target으로 변환하여 포함
+ * - scripts 패키지 → 타입체크 제외 (별도 lint만 수행)
  * 비패키지 파일 → typecheckNonPackageFiles 유틸리티
  *
  * @param options - 타입체크 실행 옵션
@@ -97,14 +97,8 @@ export async function executeTypecheck(options: TypecheckOptions): Promise<Typec
   };
 
   // sd.config.ts 로드
-  let sdConfig: SdConfig;
-  try {
-    sdConfig = await loadSdConfig({ cwd, dev: false, options: options.options });
-    logger.debug("sd.config.ts 로드 완료");
-  } catch {
-    sdConfig = { packages: {} };
-    logger.debug("sd.config.ts 로드 실패, 기본값 사용");
-  }
+  const sdConfig = await loadSdConfig({ cwd, dev: false, options: options.options });
+  logger.debug("sd.config.ts 로드 완료");
 
   // 워크스페이스 패키지 탐색 및 tests/를 설정에 병합
   const workspacePackages = discoverWorkspacePackages(cwd);
@@ -278,7 +272,7 @@ export async function executeTypecheck(options: TypecheckOptions): Promise<Typec
     formattedOutput = ts.formatDiagnosticsWithColorAndContext(uniqueDiagnostics, formatHost);
   }
 
-  // Build lint result if lint was requested
+  // lint가 요청된 경우 lint 결과 생성
   const lintResult = options.lint === true
     ? {
         success: lintSuccess,

package/src/commands/watch.ts

@@ -4,17 +4,17 @@ import {
 } from "../orchestrators/DevWatchOrchestrator";
 
 /**
- * Build all packages in watch mode.
+ * DevWatchOrchestrator를 통해 모든 패키지를 watch 모드로 빌드한다.
  *
- * - Load `sd.config.ts` to check build target info per package (required)
- * - `node`/`browser`/`neutral` target: build in esbuild watch mode + generate .d.ts
- * - `server` target: build in esbuild watch mode (no runtime)
- * - `scripts` target with watch config: run hook on file changes
- * - Auto rebuild on file changes
- * - Terminate with SIGINT/SIGTERM signals
+ * - `sd.config.ts`를 로드하여 패키지별 빌드 대상 정보를 확인한다
+ * - `node`/`browser`/`neutral` target: esbuild watch 모드 빌드 + .d.ts 생성
+ * - `server` target: esbuild watch 모드 빌드 (런타임 없음)
+ * - `scripts` target (watch 설정 있을 때): 파일 변경 시 hook 실행
+ * - 파일 변경 시 자동 재빌드
+ * - SIGINT/SIGTERM 시그널로 종료
  *
- * @param options - watch execution options (targets, options)
- * @returns resolves on termination signal
+ * @param options - watch 실행 옵션 (targets, options)
+ * @returns 종료 시그널 수신 시 resolve
  */
 export async function runWatch(options: Omit<DevWatchOrchestratorOptions, "mode">): Promise<void> {
   const orchestrator = new DevWatchOrchestrator({ mode: "watch", ...options });

package/src/electron/electron.ts

@@ -2,7 +2,7 @@ import os from "os";
 import fs from "fs";
 import module from "module";
 import { cpx, fsx, pathx } from "@simplysm/core-node";
-import { consola } from "consola";
+import { consola, LogLevels } from "consola";
 import type { SdElectronConfig } from "../sd-config.types.js";
 import { createEnvBanner } from "../utils/esbuild-config.js";
 
@@ -55,7 +55,13 @@ export class Electron {
     env?: Record<string, string>,
   ): Promise<string> {
     Electron._logger.debug(`실행: ${cmd} ${args.join(" ")}`);
-    const { stdout: result } = await cpx.exec(cmd, args, { cwd, env, shell: true });
+    const isDebug = consola.level >= LogLevels.debug;
+    const { stdout: result } = await cpx.spawn(cmd, args, {
+      cwd,
+      env,
+      shell: true,
+      ...(isDebug ? { stdio: "inherit" } : {}),
+    });
     Electron._logger.debug(`결과: ${result}`);
     return result;
   }
@@ -63,18 +69,28 @@ export class Electron {
   //#region Public Methods
 
   async initialize(): Promise<void> {
+    Electron._logger.debug("initialize 시작");
     const srcPath = pathx.posixResolve(this._electronPath, "src");
 
+    Electron._logger.debug("package.json 설정 시작");
     await this._setupPackageJson(srcPath);
+    Electron._logger.debug("package.json 설정 완료");
+
+    Electron._logger.debug("npm install 시작");
     await this._exec("npm", ["install"], srcPath);
+    Electron._logger.debug("npm install 완료");
 
     const reinstallDeps = this._config.reinstallDependencies ?? [];
     if (reinstallDeps.length > 0) {
+      Electron._logger.debug(`electron-rebuild 시작 (${reinstallDeps.join(", ")})`);
       await this._exec(this._localBin("electron-rebuild"), [], srcPath);
+      Electron._logger.debug("electron-rebuild 완료");
     }
+    Electron._logger.debug("initialize 완료");
   }
 
   async run(url: string): Promise<void> {
+    Electron._logger.debug(`run 시작 (url: ${url})`);
     const srcPath = pathx.posixResolve(this._electronPath, "src");
 
     await this.initialize();
@@ -90,12 +106,13 @@ export class Electron {
     const reinstallDeps = this._config.reinstallDependencies ?? [];
     await fsx.mkdir(srcPath);
 
-    let currentElectron: cpx.ExecProcess | null = null;
+    let currentElectron: cpx.SpawnProcess | null = null;
     let isRestarting = false;
     let resolveTermination: (() => void) | null = null;
 
     const spawnElectron = () => {
-      currentElectron = cpx.exec(this._localBin("electron"), ["."], {
+      Electron._logger.debug("Electron 프로세스 시작");
+      currentElectron = cpx.spawn(this._localBin("electron"), ["."], {
         cwd: srcPath,
         stdio: "inherit",
         reject: false,
@@ -112,6 +129,7 @@ export class Electron {
 
     const envBanner = createEnvBanner({ ELECTRON_DEV_URL: url, ...this._config.env });
 
+    Electron._logger.debug("esbuild context 생성 시작");
     const ctx = await esbuild.context({
       entryPoints: [entryPoint],
       outfile: pathx.posixResolve(srcPath, "electron-main.js"),
@@ -131,8 +149,11 @@ export class Electron {
                 return;
               }
 
+              Electron._logger.debug("esbuild 번들링 완료");
+
               if (currentElectron != null) {
                 isRestarting = true;
+                Electron._logger.debug("기존 Electron 프로세스 종료 시작");
                 currentElectron.kill();
                 try {
                   await currentElectron;
@@ -149,8 +170,11 @@ export class Electron {
         },
       ],
     });
+    Electron._logger.debug("esbuild context 생성 완료");
 
+    Electron._logger.debug("esbuild watch 시작");
     await ctx.watch();
+    Electron._logger.debug("esbuild watch 시작 완료, 종료 대기 중");
 
     await new Promise<void>((resolve) => {
       let disposed = false;
@@ -158,6 +182,7 @@ export class Electron {
       const cleanup = () => {
         if (disposed) return;
         disposed = true;
+        Electron._logger.debug("cleanup 시작");
         process.removeListener("SIGINT", signalHandler);
         process.removeListener("SIGTERM", signalHandler);
         void ctx.dispose();
@@ -167,6 +192,7 @@ export class Electron {
       resolveTermination = cleanup;
 
       const signalHandler = () => {
+        Electron._logger.debug("시그널 수신, Electron 종료 중");
         if (currentElectron != null) currentElectron.kill();
         cleanup();
       };
@@ -174,15 +200,30 @@ export class Electron {
       process.once("SIGINT", signalHandler);
       process.once("SIGTERM", signalHandler);
     });
+    Electron._logger.debug("run 완료");
   }
 
   async build(outPath: string): Promise<void> {
+    Electron._logger.debug("build 시작");
     const srcPath = pathx.posixResolve(this._electronPath, "src");
 
+    Electron._logger.debug("메인 프로세스 번들링 시작");
     await this._bundleMainProcess(srcPath);
+    Electron._logger.debug("메인 프로세스 번들링 완료");
+
+    Electron._logger.debug("웹 에셋 복사 시작");
     await this._copyWebAssets(outPath, srcPath);
+    Electron._logger.debug("웹 에셋 복사 완료");
+
+    Electron._logger.debug("electron-builder 실행 시작");
     await this._runElectronBuilder(srcPath);
+    Electron._logger.debug("electron-builder 실행 완료");
+
+    Electron._logger.debug("빌드 산출물 복사 시작");
     await this._copyBuildOutput(outPath);
+    Electron._logger.debug("빌드 산출물 복사 완료");
+
+    Electron._logger.debug("build 완료");
   }
 
   //#endregion
@@ -245,6 +286,7 @@ export class Electron {
 
     const envBanner = createEnvBanner(this._config.env);
 
+    Electron._logger.debug(`esbuild 번들링: ${entryPoint}`);
     await esbuild.build({
       entryPoints: [entryPoint],
       outfile: pathx.posixResolve(outDir, "electron-main.js"),
@@ -322,6 +364,7 @@ export class Electron {
     const configFilePath = pathx.posixResolve(this._electronPath, "builder-config.json");
     await fsx.writeJson(configFilePath, builderConfig, { space: 2 });
 
+    Electron._logger.debug(`electron-builder 설정: ${configFilePath}`);
     await this._exec(
       this._localBin("electron-builder"),
       ["--win", "--config", configFilePath],
@@ -340,6 +383,7 @@ export class Electron {
     const isPortable = this._config.portable === true;
 
     // exe 파일 동적 탐색 — Setup 또는 portable exe를 우선 선택
+    Electron._logger.debug(`빌드 산출물 탐색: ${distPath}`);
     const allExeFiles = await fsx.glob(pathx.posixResolve(distPath, "*.exe"));
     if (allExeFiles.length === 0) {
       Electron._logger.warn(`빌드 산출물(.exe)을 찾을 수 없습니다: ${distPath}`);
@@ -348,6 +392,7 @@ export class Electron {
     const keyword = isPortable ? "portable" : "Setup";
     const sourcePath =
       allExeFiles.find((f) => f.toLowerCase().includes(keyword.toLowerCase())) ?? allExeFiles[0];
+    Electron._logger.debug(`빌드 산출물: ${sourcePath}`);
 
     const latestFileName = `${safeName}${isPortable ? "-portable" : ""}-latest.exe`;
     await fsx.copy(sourcePath, pathx.posixResolve(electronOutPath, latestFileName));

package/src/engines/BaseEngine.ts

@@ -53,7 +53,7 @@ export interface BaseEngineOptions<TPkg extends PackageInfo> {
  * 이벤트 처리)이 여기에 위치하며, 서브클래스는 추상 메서드를 통해
  * 워커 경로, 빌드/워치 호출 파라미터, 타겟 결정을 제공한다.
  *
- * ViteEngine은 이 계층에 포함되지 않음 — 워커 이벤트 구조가 다름.
+ * ViteEngine은 이 계층에 포함되지 않음 — serverReady 이벤트, port 관리 등 생명주기가 다름.
  */
 export abstract class BaseEngine<
   TPkg extends PackageInfo,
@@ -189,6 +189,9 @@ export abstract class BaseEngine<
         };
         this._resultCollector?.add(result);
 
+        resolver?.();
+        resolver = undefined;
+
         // 에러 경로: 항상 resolve (reject하지 않음) — 호출자가 ResultCollector에서 상태를 확인
         if (isInitialBuild) {
           isInitialBuild = false;

package/src/engines/NgtscEngine.ts

@@ -8,24 +8,24 @@ import { consola } from "consola";
 const logger = consola.withTag("sd:cli:engine:ngtsc");
 
 /**
- * NgtscEngine options
+ * NgtscEngine 옵션
  */
 export interface NgtscEngineOptions {
   cwd: string;
   pkg: BuildPackageInfo;
-  /** replaceDeps configuration from sd.config.ts */
+  /** sd.config.ts의 replaceDeps 설정 */
   replaceDeps?: Record<string, string>;
-  /** ResultCollector for watch mode rebuild reporting */
+  /** 워치 모드 리빌드 보고용 ResultCollector */
   resultCollector?: ResultCollector;
-  /** RebuildManager for watch mode batch coordination */
+  /** 워치 모드 배치 조정용 RebuildManager */
   rebuildManager?: RebuildManager;
 }
 
 /**
- * NgtscProgram-based build engine for Angular Library packages
+ * NgtscProgram 기반 Angular 라이브러리 패키지용 빌드 엔진
  *
- * Wraps a single ngtsc-build.worker that uses NgtscProgram for AOT compilation.
- * Angular packages are detected by the presence of angularCompilerOptions in tsconfig.json.
+ * NgtscProgram을 사용하여 AOT 컴파일을 수행하는 ngtsc-build.worker를 래핑한다.
+ * package.json에 @angular/core 의존성이 있는 Angular 패키지용.
  */
 export class NgtscEngine extends BaseEngine<
   BuildPackageInfo,

package/src/engines/ServerEsbuildEngine.ts

@@ -8,24 +8,24 @@ import { consola } from "consola";
 const logger = consola.withTag("sd:cli:engine:server");
 
 /**
- * ServerEsbuildEngine options
+ * ServerEsbuildEngine 옵션
  */
 export interface ServerEsbuildEngineOptions {
   cwd: string;
   pkg: ServerPackageInfo;
-  /** replaceDeps configuration from sd.config.ts */
+  /** sd.config.ts의 replaceDeps 설정 */
   replaceDeps?: Record<string, string>;
-  /** ResultCollector for watch mode rebuild reporting */
+  /** 워치 모드 리빌드 보고용 ResultCollector */
   resultCollector?: ResultCollector;
-  /** RebuildManager for watch mode batch coordination */
+  /** 워치 모드 배치 조정용 RebuildManager */
   rebuildManager?: RebuildManager;
 }
 
 /**
- * Esbuild-based build engine for Server packages
+ * esbuild 기반 서버 패키지용 빌드 엔진
  *
- * Wraps a single server-build.worker that combines esbuild (JS bundle)
- * + tsc (typecheck) in one Worker thread.
+ * esbuild(JS 번들) + tsc(타입체크)를 하나의 Worker 스레드에서 결합하는
+ * server-build.worker를 래핑한다.
  */
 export class ServerEsbuildEngine extends BaseEngine<
   ServerPackageInfo,

package/src/engines/TscEngine.ts

@@ -8,24 +8,24 @@ import { consola } from "consola";
 const logger = consola.withTag("sd:cli:engine:tsc");
 
 /**
- * TscEngine options
+ * TscEngine 옵션
  */
 export interface TscEngineOptions {
   cwd: string;
   pkg: BuildPackageInfo;
-  /** replaceDeps configuration from sd.config.ts */
+  /** sd.config.ts의 replaceDeps 설정 */
   replaceDeps?: Record<string, string>;
-  /** ResultCollector for watch mode rebuild reporting */
+  /** 워치 모드 리빌드 보고용 ResultCollector */
   resultCollector?: ResultCollector;
-  /** RebuildManager for watch mode batch coordination */
+  /** 워치 모드 배치 조정용 RebuildManager */
   rebuildManager?: RebuildManager;
 }
 
 /**
- * tsc-based build engine for Library packages (node/browser/neutral)
+ * tsc 기반 라이브러리 패키지(node/browser/neutral)용 빌드 엔진
  *
- * Wraps a single library-build.worker that uses tsc for JS + DTS emit
- * in one Worker thread.
+ * tsc를 사용하여 JS + DTS를 emit하는 library-build.worker를
+ * 하나의 Worker 스레드에서 래핑한다.
  */
 export class TscEngine extends BaseEngine<
   BuildPackageInfo,