@simplysm/sd-cli 14.0.11 → 14.0.13

package/src/infra/ResultCollector.ts

@@ -1,5 +1,5 @@
 /**
- * Build result status
+ * 빌드 결과 상태
  */
 export interface BuildResult {
   name: string;
@@ -11,17 +11,17 @@ export interface BuildResult {
 }
 
 /**
- * Class that collects and manages build results
+ * 빌드 결과를 수집·관리하는 클래스
  *
- * Manages build results from multiple Builders at a central location and
- * provides filtering and output functionality by status.
+ * 여러 Builder의 빌드 결과를 중앙에서 관리하며,
+ * 상태별 필터링 및 출력 기능을 제공한다.
  */
 export class ResultCollector {
   private readonly _results = new Map<string, BuildResult>();
 
   /**
-   * Add result
-   * @param result build result
+   * 결과를 추가한다
+   * @param result 빌드 결과
    */
   add(result: BuildResult): void {
     const key = `${result.name}:${result.type}`;
@@ -29,15 +29,15 @@ export class ResultCollector {
   }
 
   /**
-   * Get result by key
-   * @param key result key (e.g., "core-common:build")
+   * 키로 결과를 조회한다
+   * @param key 결과 키 (예: "core-common:build")
    */
   get(key: string): BuildResult | undefined {
     return this._results.get(key);
   }
 
   /**
-   * Return internal Map (for backward compatibility)
+   * 내부 Map을 반환한다 (외부 접근용)
    */
   toMap(): Map<string, BuildResult> {
     return this._results;

package/src/infra/SignalHandler.ts

@@ -1,8 +1,8 @@
 /**
- * Class that handles process termination signals
+ * 프로세스 종료 시그널을 처리하는 클래스
  *
- * Detects SIGINT (Ctrl+C) and SIGTERM signals and
- * provides a Promise that waits until termination.
+ * SIGINT(Ctrl+C) 및 SIGTERM 시그널을 감지하고,
+ * 종료까지 대기하는 Promise를 제공한다.
  */
 export class SignalHandler {
   private _terminateResolver: (() => void) | null = null;
@@ -26,22 +26,22 @@ export class SignalHandler {
   }
 
   /**
-   * Wait until termination signal is received
+   * 종료 시그널이 수신될 때까지 대기한다
    */
   waitForTermination(): Promise<void> {
     return this._terminatePromise;
   }
 
   /**
-   * Check if terminated
+   * 종료 여부를 확인한다
    */
   isTerminated(): boolean {
     return this._terminated;
   }
 
   /**
-   * Request termination programmatically
-   * (used when triggering termination from tests or externally)
+   * 프로그래밍 방식으로 종료를 요청한다
+   * (테스트나 외부에서 종료를 트리거할 때 사용)
    */
   requestTermination(): void {
     if (!this._terminated) {

package/src/infra/WorkerManager.ts

@@ -1,19 +1,19 @@
 import { Worker, type WorkerProxy, type WorkerModule } from "@simplysm/core-node";
 
 /**
- * Class that manages Worker lifecycle
+ * Worker 생명주기를 관리하는 클래스
  *
- * Centrally manages Worker creation, lookup, and termination
- * to prevent resource leaks and provide consistent Worker management.
+ * Worker 생성, 조회, 종료를 중앙에서 관리하여
+ * 리소스 누수를 방지하고 일관된 Worker 관리를 제공한다.
  */
 export class WorkerManager {
   private readonly _workers = new Map<string, WorkerProxy<WorkerModule>>();
 
   /**
-   * Create a new Worker
-   * @param id Worker identifier (e.g., "core-common:build")
-   * @param workerPath Worker file path
-   * @returns Created WorkerProxy
+   * 새 Worker를 생성한다
+   * @param id Worker 식별자 (예: "core-common:build")
+   * @param workerPath Worker 파일 경로
+   * @returns 생성된 WorkerProxy
    */
   create<TModule extends WorkerModule>(id: string, workerPath: string): WorkerProxy<TModule> {
     const worker = Worker.create<TModule>(workerPath);
@@ -22,16 +22,16 @@ export class WorkerManager {
   }
 
   /**
-   * Lookup Worker by ID
-   * @param id Worker identifier
+   * ID로 Worker를 조회한다
+   * @param id Worker 식별자
    */
   get<TModule extends WorkerModule>(id: string): WorkerProxy<TModule> | undefined {
     return this._workers.get(id) as WorkerProxy<TModule> | undefined;
   }
 
   /**
-   * Terminate and remove a specific Worker
-   * @param id Worker identifier
+   * 특정 Worker를 종료하고 제거한다
+   * @param id Worker 식별자
    */
   async terminate(id: string): Promise<void> {
     const worker = this._workers.get(id);
@@ -42,7 +42,7 @@ export class WorkerManager {
   }
 
   /**
-   * Terminate all Workers
+   * 모든 Worker를 종료한다
    */
   async terminateAll(): Promise<void> {
     await Promise.all([...this._workers.values()].map((w) => w.terminate()));
@@ -50,14 +50,14 @@ export class WorkerManager {
   }
 
   /**
-   * Number of managed Workers
+   * 관리 중인 Worker 수
    */
   get size(): number {
     return this._workers.size;
   }
 
   /**
-   * List of all Worker IDs
+   * 모든 Worker ID 목록
    */
   get ids(): string[] {
     return [...this._workers.keys()];

package/src/orchestrators/BuildOrchestrator.ts

@@ -21,17 +21,17 @@ import { Electron } from "../electron/electron";
 //#region Types
 
 /**
- * Build Orchestrator options
+ * BuildOrchestrator 옵션
  */
 export interface BuildOrchestratorOptions {
-  /** Package filter for build (empty array includes all packages) */
+  /** 빌드 대상 패키지 필터 (빈 배열이면 전체) */
   targets: string[];
-  /** Additional options to pass to sd.config.ts */
+  /** sd.config.ts에 전달할 추가 옵션 */
   options: string[];
 }
 
 /**
- * Build result
+ * 빌드 결과
  */
 interface BuildStepResult {
   name: string;
@@ -44,14 +44,14 @@ interface BuildStepResult {
 }
 
 /**
- * Package classification result
+ * 패키지 분류 결과
  */
 interface ClassifiedPackages {
-  /** node/browser/neutral target (JS + dts) */
+  /** node/browser/neutral 대상 (JS + DTS) */
   buildPackages: Array<{ name: string; config: SdBuildPackageConfig }>;
-  /** server target (JS build, no dts) */
+  /** server 대상 (JS 빌드, DTS 없음) */
   serverPackages: Array<{ name: string; config: SdServerPackageConfig }>;
-  /** client target (Vite production build, no dts) */
+  /** client 대상 (Vite 프로덕션 빌드, DTS 없음) */
   clientPackages: Array<{ name: string; config: SdClientPackageConfig }>;
 }
 
@@ -60,11 +60,11 @@ interface ClassifiedPackages {
 //#region Utilities
 
 /**
- * Classify packages by target
- * - node/browser/neutral: buildPackages (JS + dts)
- * - server: serverPackages (JS build, no dts)
- * - client: clientPackages (Vite production build, no dts)
- * - scripts: excluded
+ * 패키지를 target별로 분류
+ * - node/browser/neutral: buildPackages (JS + DTS)
+ * - server: serverPackages (JS 빌드, DTS 없음)
+ * - client: clientPackages (Vite 프로덕션 빌드, DTS 없음)
+ * - scripts: 제외
  */
 export function classifyPackages(
   packages: Record<
@@ -97,7 +97,7 @@ export function classifyPackages(
 }
 
 /**
- * Delete dist folders
+ * dist 폴더 삭제
  */
 async function cleanDistFolders(cwd: string, packageNames: string[]): Promise<void> {
   await Promise.all(packageNames.map((name) => fsx.rm(pathx.posixResolve(cwd, "packages", name, "dist"))));
@@ -108,14 +108,14 @@ async function cleanDistFolders(cwd: string, packageNames: string[]): Promise<vo
 //#region BuildOrchestrator
 
 /**
- * Orchestrator for coordinating production builds
+ * 프로덕션 빌드를 조율하는 Orchestrator
  *
- * Classifies packages based on sd.config.ts and executes builds.
- * - Clean dist folders (clean build)
- * - Run lint + build concurrently
- * - node/browser/neutral targets: esbuild JS build + dts generation
- * - server targets: esbuild JS build
- * - client targets: Vite production build
+ * sd.config.ts 기반으로 패키지를 분류하고 빌드를 실행한다.
+ * - dist 폴더 정리 (클린 빌드)
+ * - lint + 빌드 동시 실행
+ * - 라이브러리 패키지: TscEngine/NgtscEngine으로 JS + DTS 빌드
+ * - 서버 패키지: BuildEngine으로 JS 빌드
+ * - 클라이언트 패키지: ViteEngine으로 Vite 프로덕션 빌드
  */
 export class BuildOrchestrator {
   private readonly _cwd: string;
@@ -183,12 +183,12 @@ export class BuildOrchestrator {
   }
 
   /**
-   * Execute build
-   * - Clean
-   * - Lint + Build (concurrent)
-   * - Output results
+   * 빌드 실행
+   * - 클린
+   * - lint + 빌드 (동시 실행)
+   * - 결과 출력
    *
-   * @returns whether errors occurred (true: errors present)
+   * @returns 에러 발생 여부 (true: 에러 있음)
    */
   async start(): Promise<boolean> {
     if (this._allPackageNames.length === 0) {
@@ -198,15 +198,15 @@ export class BuildOrchestrator {
     const classified = this._classified!;
     const baseEnv = this._baseEnv!;
 
-    // Collect results
+    // 결과 수집
     const results: BuildStepResult[] = [];
-    // Track errors (wrapped in object to allow mutation tracking in callbacks)
+    // 에러 추적 (콜백에서 변경 추적을 위해 객체로 래핑)
     const state = { hasError: false };
 
-    // File cache (for diagnostics output)
+    // 파일 캐시 (진단 출력용)
     const fileCache = new Map<string, string>();
 
-    // formatHost (for diagnostics output)
+    // formatHost (진단 출력용)
     const formatHost: ts.FormatDiagnosticsHost = {
       getCanonicalFileName: (f) => f,
       getCurrentDirectory: () => this._cwd,
@@ -221,10 +221,10 @@ export class BuildOrchestrator {
     // Phase 2: 빌드
     const concurrency = getMaxConcurrency();
 
-    // Create list of build tasks
+    // 빌드 태스크 목록 생성
     const buildTasks: Array<() => Promise<void>> = [];
 
-    // buildPackages: JS build + dts generation via BuildEngine
+    // 라이브러리 패키지: BuildEngine으로 JS + DTS 빌드
     for (const { name, config } of classified.buildPackages) {
       const pkgDir = pathx.posixResolve(this._cwd, "packages", name);
 
@@ -276,7 +276,7 @@ export class BuildOrchestrator {
       });
     }
 
-    // serverPackages: JS build + typecheck via BuildEngine
+    // 서버 패키지: BuildEngine으로 JS 빌드 + 타입체크
     for (const { name, config } of classified.serverPackages) {
       const pkgDir = pathx.posixResolve(this._cwd, "packages", name);
 
@@ -322,15 +322,19 @@ export class BuildOrchestrator {
       });
     }
 
-    // clientPackages: Vite production build via ViteEngine (no dts)
+    // 클라이언트 패키지: ViteEngine으로 Vite 프로덕션 빌드 (DTS 없음)
     for (const { name, config } of classified.clientPackages) {
       const pkgDir = pathx.posixResolve(this._cwd, "packages", name);
 
       buildTasks.push(async () => {
         this._logger.debug(`[${name}] (client) 빌드 시작`);
+        const isNativeBuild = config.capacitor != null || config.electron != null;
+        const outDir = config.capacitor != null
+          ? pathx.posixResolve(pkgDir, ".capacitor/www")
+          : undefined;
         const engine = createBuildEngine(
           { name, dir: pkgDir, config: { ...config, env: { ...baseEnv, ...config.env } } },
-          { cwd: this._cwd },
+          { cwd: this._cwd, outDir, base: isNativeBuild ? "" : undefined },
         );
 
         try {
@@ -471,11 +475,11 @@ export class BuildOrchestrator {
   }
 
   /**
-   * Shutdown Orchestrator (no resources to clean up currently)
+   * Orchestrator 종료 (현재 정리할 리소스 없음)
    */
   async shutdown(): Promise<void> {
-    // Production builds are one-time operations, so there are no resources to clean up at shutdown
-    // Workers are cleaned up with terminate() within each build task
+    // 프로덕션 빌드는 일회성 작업이므로 종료 시 정리할 리소스가 없음
+    // Worker는 각 빌드 태스크 내에서 terminate()로 정리됨
     await Promise.resolve();
   }
 }

package/src/orchestrators/DevWatchOrchestrator.ts

@@ -25,12 +25,12 @@ import type * as ServerRuntimeWorkerModule from "../workers/server-runtime.worke
 import type { ServerReadyEventData, ErrorEventData } from "../utils/worker-events";
 
 /**
- * Orchestrator mode
+ * Orchestrator 모드
  */
 export type OrchestratorMode = "watch" | "dev";
 
 /**
- * DevWatchOrchestrator options
+ * DevWatchOrchestrator 옵션
  */
 export interface DevWatchOrchestratorOptions {
   mode: OrchestratorMode;
@@ -39,26 +39,26 @@ export interface DevWatchOrchestratorOptions {
 }
 
 /**
- * Unified Orchestrator for watch and dev modes.
+ * watch/dev 모드 통합 Orchestrator
  *
- * - watch: Library(js+dts) + Scripts(watch hook) + copySrc + replaceDeps
- * - dev: Server(js+runtime) + client-ready(skip) + replaceDeps
+ * - watch: 라이브러리(JS+DTS) + Scripts(watch hook) + copySrc + replaceDeps
+ * - dev: 서버(JS+런타임) + 클라이언트 준비(skip) + replaceDeps
  */
 export class DevWatchOrchestrator {
   private readonly _cwd: string;
   private readonly _options: DevWatchOrchestratorOptions;
   private readonly _logger;
 
-  // Infrastructure
+  // 인프라
   private _resultCollector!: ResultCollector;
   private _signalHandler!: SignalHandler;
   private _rebuildManager!: RebuildManager;
 
-  // Engines
+  // 엔진
   private readonly _libraryEngines: BuildEngine[] = [];
   private readonly _serverEngines = new Map<string, BuildEngine>();
 
-  // Package info
+  // 패키지 정보
   private _libraryPackages: BuildPackageInfo[] = [];
   private _serverPackages: Array<{ name: string; dir: string; config: SdServerPackageConfig }> = [];
   private _watchHookPackages: Array<{ name: string; dir: string; config: SdScriptsPackageConfig | SdBuildPackageConfig }> = [];
@@ -66,13 +66,13 @@ export class DevWatchOrchestrator {
   private readonly _clientEngines = new Map<string, BuildEngine>();
   private _serverClientsMap = new Map<string, string[]>();
 
-  // Dev mode: runtime workers
+  // dev 모드: 런타임 워커
   private _baseEnv: { VER: string; DEV: string } | undefined;
   private readonly _serverRuntimeWorkers = new Map<string, WorkerProxy<typeof ServerRuntimeWorkerModule>>();
   private _printServersTimer: ReturnType<typeof setTimeout> | undefined;
   private _serverRestartTimer: ReturnType<typeof setTimeout> | undefined;
 
-  // Watchers
+  // 워처
   private _copySrcWatchers: FsWatcher[] = [];
   private readonly _watchHookWatchers: FsWatcher[] = [];
   private readonly _watchHookChildren = new Map<string, ChildProcess>();
@@ -106,30 +106,30 @@ export class DevWatchOrchestrator {
       throw err;
     }
 
-    // Build pathMap from config packages only (tests packages are excluded from watch/dev)
+    // config 패키지에서 pathMap 빌드 (tests 패키지는 watch/dev에서 제외)
     this._pathMap = buildPathMapFromConfig(sdConfig.packages);
 
-    // Validate targets
+    // 대상 유효성 검사
     validateTargets(this._options.targets, sdConfig.packages);
 
-    // Store replaceDeps for engine creation
+    // 엔진 생성을 위해 replaceDeps 저장
     this._replaceDeps = sdConfig.replaceDeps;
 
-    // Start watch if replaceDeps config exists
+    // replaceDeps 설정이 있으면 watch 시작
     if (sdConfig.replaceDeps != null) {
       this._replaceDepWatcher = await watchReplaceDeps(this._cwd, sdConfig.replaceDeps);
     }
 
-    // Prepare VER, DEV environment variables for dev mode
+    // dev 모드용 VER, DEV 환경변수 준비
     if (this._options.mode === "dev") {
       const version = await getVersion(this._cwd);
       this._baseEnv = { VER: version, DEV: "true" };
     }
 
-    // Filter by targets
+    // 대상으로 필터링
     const allPackages = filterPackagesByTargets(sdConfig.packages, this._options.targets);
 
-    // Classify packages based on mode
+    // 모드에 따라 패키지 분류
     if (this._options.mode === "watch") {
       const classified = classifyWatchPackages(allPackages, this._cwd, this._pathMap);
       this._libraryPackages = classified.libraryPackages;
@@ -141,7 +141,7 @@ export class DevWatchOrchestrator {
       this._serverClientsMap = classified.serverClientsMap;
     }
 
-    // Check if there are packages to process
+    // 처리할 패키지가 있는지 확인
     const totalPackages = this._libraryPackages.length + this._serverPackages.length + this._watchHookPackages.length + this._clientPackages.length;
     if (totalPackages === 0) {
       const modeLabel = this._options.mode === "watch" ? "워치" : "개발";
@@ -151,12 +151,12 @@ export class DevWatchOrchestrator {
 
     this._hasPackages = true;
 
-    // Initialize infrastructure
+    // 인프라 초기화
     this._signalHandler = new SignalHandler();
     this._resultCollector = new ResultCollector();
     this._rebuildManager = new RebuildManager(this._logger);
 
-    // Batch complete handler
+    // 배치 완료 핸들러
     if (this._options.mode === "watch") {
       this._rebuildManager.on("batchComplete", (_completedKeys) => {
         printErrors(this._resultCollector.toMap());
@@ -167,7 +167,7 @@ export class DevWatchOrchestrator {
       });
     }
 
-    // Create BuildEngines for library packages (watch mode only)
+    // 라이브러리 패키지용 BuildEngine 생성 (watch 모드 전용)
     for (const pkg of this._libraryPackages) {
       const engine = createBuildEngine(pkg, {
         cwd: this._cwd,
@@ -178,7 +178,7 @@ export class DevWatchOrchestrator {
       this._libraryEngines.push(engine);
     }
 
-    // Create BuildEngines for server packages
+    // 서버 패키지용 BuildEngine 생성
     for (const { name, dir, config } of this._serverPackages) {
       const engineConfig = this._options.mode === "dev"
         ? { ...config, env: { ...this._baseEnv, ...config.env } }
@@ -196,7 +196,7 @@ export class DevWatchOrchestrator {
       this._serverEngines.set(name, engine);
     }
 
-    // Create BuildEngines for client packages (dev mode only)
+    // 클라이언트 패키지용 BuildEngine 생성 (dev 모드 전용)
     const resolvedReplaceDeps = this._replaceDepWatcher?.entries.map((e) => ({
       packageName: e.targetName,
       sourcePath: e.resolvedSourcePath,
@@ -249,16 +249,16 @@ export class DevWatchOrchestrator {
 
     const shutdownTasks: Array<Promise<void>> = [];
 
-    // Stop all engines
+    // 모든 엔진 중지
     shutdownTasks.push(...this._libraryEngines.map((e) => e.stop()));
     shutdownTasks.push(...[...this._serverEngines.values()].map((e) => e.stop()));
     shutdownTasks.push(...[...this._clientEngines.values()].map((e) => e.stop()));
 
-    // Close watchers (watch mode)
+    // 워처 종료 (watch 모드)
     shutdownTasks.push(...this._copySrcWatchers.map((w) => w.close()));
     shutdownTasks.push(...this._watchHookWatchers.map((w) => w.close()));
 
-    // Kill hook child processes
+    // hook 자식 프로세스 종료
     for (const child of this._watchHookChildren.values()) {
       if (child.exitCode == null) {
         child.kill();
@@ -266,7 +266,7 @@ export class DevWatchOrchestrator {
     }
     this._watchHookChildren.clear();
 
-    // Terminate runtime workers (dev mode)
+    // 런타임 워커 종료 (dev 모드)
     shutdownTasks.push(...[...this._serverRuntimeWorkers.values()].map((w) => w.terminate()));
 
     await Promise.all(shutdownTasks);
@@ -277,7 +277,7 @@ export class DevWatchOrchestrator {
     process.stdout.write("✔ 종료 완료\n");
   }
 
-  // --- Watch mode ---
+  // --- watch 모드 ---
 
   private async _startWatchMode(): Promise<void> {
     this._logger.debug("watch 모드 시작");
@@ -346,7 +346,7 @@ export class DevWatchOrchestrator {
     });
   }
 
-  // --- Dev mode ---
+  // --- dev 모드 ---
 
   private async _startDevMode(): Promise<void> {
     // Start client and server engines in parallel
@@ -380,7 +380,7 @@ export class DevWatchOrchestrator {
       }
     });
 
-    // Register standalone client results in ResultCollector
+    // 독립 클라이언트 결과를 ResultCollector에 등록
     for (const { name } of this._clientPackages) {
       const isServerConnected = [...this._serverClientsMap.values()].some(
         (clients) => clients.includes(name),
@@ -399,7 +399,7 @@ export class DevWatchOrchestrator {
       }
     }
 
-    // Initialize Capacitor for client packages (device execution is handled by the `device` command)
+    // 클라이언트 패키지의 Capacitor 초기화 (디바이스 실행은 'device' 명령어가 담당)
     for (const { name, config } of this._clientPackages) {
       const port = this._getClientPort(name);
       if (port == null) continue;
@@ -474,13 +474,13 @@ export class DevWatchOrchestrator {
     }, 300);
   }
 
-  /** Get port from a client engine (duck-typing for ViteEngine.port) */
+  /** 클라이언트 엔진에서 포트 가져오기 (ViteEngine.port에 대한 duck-typing) */
   private _getClientPort(name: string): number | undefined {
     const engine = this._clientEngines.get(name) as { port?: number } | undefined;
     return engine?.port;
   }
 
-  /** Collect client ports for a server's connected clients */
+  /** 서버에 연결된 클라이언트들의 포트 수집 */
   private _collectClientPorts(serverName: string): Record<string, number> {
     const clientPorts: Record<string, number> = {};
     const connectedClients = this._serverClientsMap.get(serverName) ?? [];
@@ -501,19 +501,19 @@ export class DevWatchOrchestrator {
   ): Promise<void> {
     this._logger.debug(`[${serverName}] 서버 런타임 시작: ${mainJsPath}`);
 
-    // Terminate existing runtime
+    // 기존 런타임 종료
     const existingRuntime = this._serverRuntimeWorkers.get(serverName);
     if (existingRuntime != null) {
       this._logger.info(`[${serverName}] 서버 재시작 중...`);
       await existingRuntime.terminate();
     }
 
-    // Create and start new runtime worker
+    // 새 런타임 워커 생성 및 시작
     const runtimeWorkerPath = import.meta.resolve("../workers/server-runtime.worker");
     const runtimeWorker = Worker.create<typeof ServerRuntimeWorkerModule>(runtimeWorkerPath);
     this._serverRuntimeWorkers.set(serverName, runtimeWorker);
 
-    // Runtime event handlers
+    // 런타임 이벤트 핸들러
     runtimeWorker.on("serverReady", (readyData) => {
       const readyEvent = readyData as ServerReadyEventData;
       this._resultCollector.add({

package/src/sd-cli-entry.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /* eslint-disable no-console */
 
-// side-effect: Map/Array prototype extensions (getOrCreate, etc.)
+// 사이드 이펙트: Map/Array prototype 확장 (getOrCreate 등)
 import "@simplysm/core-common";
 import yargs, { type Argv } from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -34,7 +34,7 @@ async function collectYargsHelp(argv: string[]): Promise<string> {
   try {
     await createCliParser(argv).exitProcess(false).parse();
   } catch {
-    // yargs may throw after help display
+    // yargs가 help 출력 후 throw할 수 있음
   } finally {
   
     console.log = orig;
@@ -43,11 +43,11 @@ async function collectYargsHelp(argv: string[]): Promise<string> {
 }
 
 /**
- * Create CLI parser
- * @internal exported for testing
+ * CLI 파서 생성
+ * @internal 테스트용으로 export
  */
 export function createCliParser(argv: string[]): Argv {
-  // Top-level --help/-h (without a subcommand): show comprehensive help for all commands
+  // 최상위 --help/-h (서브커맨드 없이): 모든 명령어의 종합 도움말 표시
   const hasHelp = argv.includes("--help") || argv.includes("-h");
   const hasCommand = COMMAND_NAMES.some((cmd) => argv.includes(cmd));
   if (hasHelp && !hasCommand) {
@@ -313,11 +313,18 @@ export function createCliParser(argv: string[]): Argv {
       },
     )
     .demandCommand(1, "Please specify a command.")
-    .strict();
+    .strict()
+    .fail((msg, err) => {
+      if (msg) {
+        consola.error(msg);
+        process.exit(1);
+      }
+      throw err;
+    });
 }
 
-// Parse only when executed directly as CLI
-// Determine main module in ESM: normalize import.meta.url and process.argv[1] and compare
+// CLI로 직접 실행될 때만 파싱
+// ESM에서 메인 모듈 판별: import.meta.url과 process.argv[1]을 정규화하여 비교
 const cliEntryPath = process.argv.at(1);
 if (
   cliEntryPath != null &&