@simplysm/sd-cli 14.0.11 → 14.0.13

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,

package/src/engines/ViteEngine.ts

@@ -20,6 +20,10 @@ export interface ViteEngineOptions {
   rebuildManager?: RebuildManager;
   /** sdScopeWatchPlugin용 replaceDeps 항목 */
   replaceDeps?: Array<{ packageName: string; sourcePath: string }>;
+  /** 빌드 출력 경로 (미설정 시 pkgDir/dist) */
+  outDir?: string;
+  /** Vite base 경로 (미설정 시 /{pkgName}/) */
+  base?: string;
 }
 
 /**
@@ -34,6 +38,8 @@ export class ViteEngine implements BuildEngine {
   private readonly _resultCollector: ResultCollector | undefined;
   private readonly _rebuildManager: RebuildManager | undefined;
   private readonly _replaceDeps: Array<{ packageName: string; sourcePath: string }> | undefined;
+  private readonly _outDir: string | undefined;
+  private readonly _base: string | undefined;
 
   private _worker: WorkerProxy<typeof ClientWorkerModule> | undefined;
   private _isWatchMode = false;
@@ -47,6 +53,8 @@ export class ViteEngine implements BuildEngine {
     this._resultCollector = options.resultCollector;
     this._rebuildManager = options.rebuildManager;
     this._replaceDeps = options.replaceDeps;
+    this._outDir = options.outDir;
+    this._base = options.base;
   }
 
   /**
@@ -64,6 +72,9 @@ export class ViteEngine implements BuildEngine {
       configs: this._pkg.config.configs,
       browserSupport: this._pkg.config.browserSupport,
       enableLint: output.lint,
+      exclude: this._pkg.config.exclude,
+      outDir: this._outDir,
+      base: this._base,
     });
 
     logger.debug(`[${this._pkg.name}] ViteEngine.run 완료 (success: ${result.success})`);
@@ -81,7 +92,7 @@ export class ViteEngine implements BuildEngine {
 
   /**
    * 워치 모드 시작 (Vite 개발 서버)
-   * 개발 서버가 준비되면 Promise가 resolve된다.
+   * worker의 startWatch()가 완료되면 Promise가 resolve된다.
    */
   async startWatch(output: BuildOutput): Promise<void> {
     logger.debug(`[${this._pkg.name}] ViteEngine.startWatch 시작`);
@@ -94,7 +105,7 @@ export class ViteEngine implements BuildEngine {
       this.port = event.port;
     });
 
-    // 리빌드 이벤트 처리 (Feature 3.3 HMR)
+    // 리빌드 이벤트 처리 (HMR)
     let resolver: (() => void) | undefined;
     const workerKey = `vite:${this._pkg.name}`;
 
@@ -152,6 +163,9 @@ export class ViteEngine implements BuildEngine {
         message: event.message,
       };
       this._resultCollector?.add(buildResult);
+
+      resolver?.();
+      resolver = undefined;
     });
 
     const port =
@@ -159,7 +173,7 @@ export class ViteEngine implements BuildEngine {
         ? this._pkg.config.server
         : undefined;
 
-    const result = await this._worker!.startWatch({
+    await this._worker!.startWatch({
       name: this._pkg.name,
       cwd: this._cwd,
       pkgDir: this._pkg.dir,
@@ -169,17 +183,8 @@ export class ViteEngine implements BuildEngine {
       replaceDeps: this._replaceDeps,
       browserSupport: this._pkg.config.browserSupport,
       enableLint: output.lint,
+      exclude: this._pkg.config.exclude,
     });
-
-    // 초기 빌드 결과 보고
-    const buildResult: BuildResult = {
-      name: this._pkg.name,
-      target: "client",
-      type: "build",
-      status: result.success ? "success" : "error",
-      message: result.errors?.join("\n"),
-    };
-    this._resultCollector?.add(buildResult);
   }
 
   /**

package/src/engines/index.ts

@@ -23,12 +23,12 @@ export type { ViteEngineOptions } from "./ViteEngine";
 export type { BuildEngine, BuildOutput, BuildPackageInfo, ClientPackageInfo, EngineResult, PackageInfo, ServerPackageInfo } from "./types";
 
 /**
- * Create a BuildEngine for the given package.
+ * 주어진 패키지에 맞는 BuildEngine을 생성한다.
  *
- * Client packages use ViteEngine (Angular buildApplicationInternal / serveWithVite).
- * Server packages use ServerEsbuildEngine.
- * Angular Library packages (detected by @angular/core in package.json) use NgtscEngine.
- * Other Library packages (node/browser/neutral) use TscEngine.
+ * 클라이언트 패키지는 ViteEngine을 사용한다.
+ * 서버 패키지는 ServerEsbuildEngine을 사용한다.
+ * Angular 라이브러리 패키지(package.json에 @angular/core 의존성 감지)는 NgtscEngine을 사용한다.
+ * 기타 라이브러리 패키지(node/browser/neutral)는 TscEngine을 사용한다.
  */
 export function createBuildEngine(
   pkg: BuildPackageInfo | ServerPackageInfo | ClientPackageInfo,
@@ -38,6 +38,10 @@ export function createBuildEngine(
     resolvedReplaceDeps?: Array<{ packageName: string; sourcePath: string }>;
     resultCollector?: ResultCollector;
     rebuildManager?: RebuildManager;
+    /** 클라이언트 빌드 출력 경로 (ViteEngine에만 적용) */
+    outDir?: string;
+    /** Vite base 경로 (ViteEngine에만 적용, 미설정 시 /{pkgName}/) */
+    base?: string;
   },
 ): BuildEngine {
   if (pkg.config.target === "client") {
@@ -48,6 +52,8 @@ export function createBuildEngine(
       resultCollector: options.resultCollector,
       rebuildManager: options.rebuildManager,
       replaceDeps: options.resolvedReplaceDeps,
+      outDir: options.outDir,
+      base: options.base,
     });
   }
 

package/src/engines/types.ts

@@ -4,7 +4,7 @@ import type { TypecheckEnv } from "../utils/tsconfig";
 import type { LintWithProgramResult } from "../utils/lint-with-program";
 
 /**
- * Package information
+ * 패키지 정보
  */
 export interface PackageInfo {
   name: string;
@@ -13,36 +13,36 @@ export interface PackageInfo {
 }
 
 /**
- * PackageInfo narrowed for build packages (node/browser/neutral)
+ * 빌드 패키지(node/browser/neutral)로 좁혀진 PackageInfo
  */
 export type BuildPackageInfo = PackageInfo & { config: SdBuildPackageConfig };
 
 /**
- * PackageInfo narrowed for server packages
+ * 서버 패키지로 좁혀진 PackageInfo
  */
 export type ServerPackageInfo = PackageInfo & { config: SdServerPackageConfig };
 
 /**
- * PackageInfo narrowed for client packages
+ * 클라이언트 패키지로 좁혀진 PackageInfo
  */
 export type ClientPackageInfo = PackageInfo & { config: SdClientPackageConfig };
 
 /**
- * Build output control flags
+ * 빌드 출력 제어 플래그
  */
 export interface BuildOutput {
   js: boolean;
   dts: boolean;
-  /** When true, run ESLint using the ts.Program created during typecheck. */
+  /** true일 때, 타입체크 중 생성된 ts.Program으로 ESLint를 실행한다. */
   lint?: boolean;
-  /** Typecheck environment. When set, adjusts compilerOptions via getCompilerOptionsForEnv(). */
+  /** 타입체크 환경. 설정 시 getCompilerOptionsForEnv()를 통해 compilerOptions를 조정한다. */
   env?: TypecheckEnv;
-  /** Include tests/ files in typecheck scope. Only used by check command. */
+  /** 타입체크 범위에 tests/ 파일을 포함한다. check 커맨드에서만 사용된다. */
   includeTests?: boolean;
 }
 
 /**
- * BuildEngine.run() return value
+ * BuildEngine.run() 반환값
  */
 export interface EngineResult {
   success: boolean;
@@ -52,33 +52,33 @@ export interface EngineResult {
     warnings: string[];
     diagnostics: SerializedDiagnostic[];
   };
-  /** Lint result (present when BuildOutput.lint is true) */
+  /** 린트 결과 (BuildOutput.lint가 true일 때 존재) */
   lint?: LintWithProgramResult;
 }
 
 /**
- * Build engine interface
+ * 빌드 엔진 인터페이스
  *
- * Common contract for all build engines.
- * typecheck (diagnostics) is always included — not optional.
+ * 모든 빌드 엔진의 공통 계약.
+ * 타입체크(diagnostics)는 항상 포함되며 선택사항이 아니다.
  */
 export interface BuildEngine {
   /**
-   * One-time build (for production builds)
-   * Creates workers, runs build, returns combined result.
-   * Call stop() after to clean up resources.
+   * 일회성 빌드 (프로덕션)
+   * Worker를 생성하고, 빌드를 실행하고, 결합된 결과를 반환한다.
+   * 호출 후 stop()으로 리소스를 정리한다.
    */
   run(output: BuildOutput): Promise<EngineResult>;
 
   /**
-   * Start watch mode
-   * Promise resolves when initial build is complete.
-   * Subsequent rebuilds are reported via injected ResultCollector.
+   * 워치 모드 시작
+   * 초기 빌드가 완료되면 Promise가 resolve된다.
+   * 이후 리빌드는 주입된 ResultCollector를 통해 보고된다.
    */
   startWatch(output: BuildOutput): Promise<void>;
 
   /**
-   * Stop engine and clean up resources (workers, esbuild contexts)
+   * 엔진을 중지하고 리소스(Worker, esbuild context 등)를 정리한다
    */
   stop(): Promise<void>;
 }