@simplysm/sd-cli 14.0.10 → 14.0.12

package/src/orchestrators/DevWatchOrchestrator.ts

@@ -21,17 +21,16 @@ import { SignalHandler } from "../infra/SignalHandler";
 import { createBuildEngine, type BuildEngine, type BuildPackageInfo, type ClientPackageInfo, type ServerPackageInfo } from "../engines/index";
 import { watchCopySrcFiles } from "../utils/copy-src";
 import { Capacitor } from "../capacitor/capacitor";
-import { Electron } from "../electron/electron";
 import type * as ServerRuntimeWorkerModule from "../workers/server-runtime.worker";
 import type { ServerReadyEventData, ErrorEventData } from "../utils/worker-events";
 
 /**
- * Orchestrator mode
+ * Orchestrator 모드
  */
 export type OrchestratorMode = "watch" | "dev";
 
 /**
- * DevWatchOrchestrator options
+ * DevWatchOrchestrator 옵션
  */
 export interface DevWatchOrchestratorOptions {
   mode: OrchestratorMode;
@@ -40,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 }> = [];
@@ -67,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>();
@@ -107,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;
@@ -142,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" ? "워치" : "개발";
@@ -152,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());
@@ -168,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,
@@ -179,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 } }
@@ -197,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,
@@ -250,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();
@@ -267,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);
@@ -278,7 +277,7 @@ export class DevWatchOrchestrator {
     process.stdout.write("✔ 종료 완료\n");
   }
 
-  // --- Watch mode ---
+  // --- watch 모드 ---
 
   private async _startWatchMode(): Promise<void> {
     this._logger.debug("watch 모드 시작");
@@ -347,7 +346,7 @@ export class DevWatchOrchestrator {
     });
   }
 
-  // --- Dev mode ---
+  // --- dev 모드 ---
 
   private async _startDevMode(): Promise<void> {
     // Start client and server engines in parallel
@@ -381,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),
@@ -400,46 +399,23 @@ export class DevWatchOrchestrator {
       }
     }
 
-    // Start native apps for client packages with capacitor/electron config
+    // 클라이언트 패키지의 Capacitor 초기화 (디바이스 실행은 'device' 명령어가 담당)
     for (const { name, config } of this._clientPackages) {
       const port = this._getClientPort(name);
       if (port == null) continue;
 
-      const devServerUrl = `http://localhost:${port}`;
       const pkgDir = pathx.posixResolve(this._cwd, "packages", name);
 
       if (config.capacitor != null) {
         try {
           const cap = await Capacitor.create(pkgDir, config.capacitor, config.exclude);
           await cap.initialize();
-          await cap.run(devServerUrl);
         } catch (err) {
           this._logger.error(
-            `[${name}] Capacitor 실행 실패: ${errNs.message(err)}`,
+            `[${name}] Capacitor 초기화 실패: ${errNs.message(err)}`,
           );
         }
       }
-
-      if (config.electron != null) {
-        void (async () => {
-          try {
-            const elc = await Electron.create(pkgDir, config.electron!, config.exclude);
-            await elc.initialize();
-            await elc.run(devServerUrl);
-          } catch (err) {
-            this._logger.error(
-              `[${name}] Electron 실행 실패: ${errNs.message(err)}`,
-            );
-            this._resultCollector.add({
-              name,
-              target: "client",
-              type: "build",
-              status: "error",
-              message: `Electron 실행 실패: ${errNs.message(err)}`,
-            });
-          }
-        })();
-      }
     }
 
     // Print initial results
@@ -498,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) ?? [];
@@ -525,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";
@@ -23,7 +23,7 @@ EventEmitter.defaultMaxListeners = 100;
 
 consola.options.reporters = [new SdCliReporter()];
 
-const COMMAND_NAMES = ["check", "watch", "dev", "build", "publish", "replace-deps"];
+const COMMAND_NAMES = ["check", "watch", "dev", "device", "build", "publish", "replace-deps"];
 
 async function collectYargsHelp(argv: string[]): Promise<string> {
   const lines: string[] = [];
@@ -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) {
@@ -185,6 +185,41 @@ export function createCliParser(argv: string[]): Argv {
         });
       },
     )
+    .command(
+      "device",
+      "Run native app on device/desktop",
+      (cmd) =>
+        cmd
+          .version(false)
+          .hide("help")
+          .options({
+            "package": {
+              type: "string",
+              alias: "p",
+              description: "Client package name to run",
+              demandOption: true,
+            },
+            "url": {
+              type: "string",
+              description: "Dev server URL (auto-detected from sd.config.ts if omitted)",
+            },
+            "opt": {
+              type: "string",
+              array: true,
+              alias: "o",
+              description: "Options to pass to sd.config.ts (e.g., -o key=value)",
+              default: [] as string[],
+            },
+          }),
+      async (args) => {
+        const { runDevice } = await import("./commands/device");
+        await runDevice({
+          package: args.package,
+          url: args.url,
+          options: args.opt,
+        });
+      },
+    )
     .command(
       "build [targets..]",
       "Run production build",
@@ -278,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 &&

package/src/sd-cli.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * CLI Launcher
+ * CLI 런처
  *
- * .ts execution (dev): apply CPU affinity then directly import sd-cli-entry
- * .js execution (production): run replaceDeps then spawn sd-cli-entry in new process
+ * .ts 실행 (개발): CPU affinity 적용 후 sd-cli-entry를 직접 import
+ * .js 실행 (프로덕션): replaceDeps 실행 후 새 프로세스에서 sd-cli-entry 실행
  */
 
 import { cpx } from "@simplysm/core-node";
@@ -17,16 +17,16 @@ const __dirname = path.dirname(__filename);
 const isDev = path.extname(__filename) === ".ts";
 
 if (isDev) {
-  // Dev mode (.ts): apply affinity then run directly
-  // Main module detection fails with import only (process.argv[1] ≠ sd-cli-entry)
-  // so createCliParser must be called explicitly.
+  // 개발 모드 (.ts): affinity 적용 후 직접 실행
+  // import만으로는 메인 모듈 판별이 실패하므로 (process.argv[1] ≠ sd-cli-entry)
+  // createCliParser를 명시적으로 호출해야 한다.
   configureAffinityAndPriority(process.pid);
   const { createCliParser } = await import("./sd-cli-entry.js");
   await createCliParser(process.argv.slice(2)).parse();
 } else {
   // Production mode (.js): two-stage execution
 
-  // Phase 1: replaceDeps (inline — copy to installed version)
+  // Phase 1: replaceDeps (인라인 — 설치된 버전으로 복사)
   try {
     const { loadSdConfig } = await import("./utils/sd-config.js");
     const { setupReplaceDeps } = await import("./utils/replace-deps.js");
@@ -35,12 +35,12 @@ if (isDev) {
       await setupReplaceDeps(process.cwd(), sdConfig.replaceDeps);
     }
   } catch {
-    // Skip if sd.config.ts is missing or replaceDeps is not configured
+    // sd.config.ts가 없거나 replaceDeps가 설정되지 않으면 건너뜀
   }
 
-  // Phase 2: Run actual CLI in new process (reset module cache)
+  // Phase 2: 실제 CLI를 새 프로세스로 실행 (모듈 캐시 초기화)
   const cliEntryFilePath = path.join(__dirname, "sd-cli-entry.js");
-  const subprocess = cpx.exec(
+  const subprocess = cpx.spawn(
     "node",
     [
       "--max-old-space-size=8192",
@@ -56,10 +56,10 @@ if (isDev) {
 }
 
 /**
- * Calculate CPU affinity mask (exclude front cores)
+ * CPU affinity 마스크 계산 (앞쪽 코어 제외)
  *
- * Exclude 1 core per 4 CPUs, then set bits ON for remaining cores.
- * Example: 8 cores → exclude 2 → 0xFC (cores 2~7)
+ * CPU 4개당 1개 코어를 제외하고, 나머지 코어의 비트를 ON으로 설정한다.
+ * 예시: 8코어 → 2개 제외 → 0xFC (코어 2~7)
  */
 function calculateAffinityMask(cpuCount: number): string {
   const exclude = cpuCount <= 1 ? 0 : Math.ceil(cpuCount / 4);
@@ -71,12 +71,12 @@ function calculateAffinityMask(cpuCount: number): string {
 }
 
 /**
- * Configure CPU affinity and priority (cross-platform)
+ * CPU affinity 및 우선순위 설정 (크로스 플랫폼)
  *
  * - Windows: PowerShell ProcessorAffinity + PriorityClass
  * - Linux/WSL: taskset + renice
  *
- * Only print warning on failure; does not affect CLI operation.
+ * 실패 시 경고만 출력하며, CLI 동작에는 영향을 주지 않는다.
  */
 function configureAffinityAndPriority(pid: number): void {
   const cpuCount = os.cpus().length;
@@ -94,7 +94,7 @@ function configureAffinityAndPriority(pid: number): void {
     command = `taskset -p ${mask} ${pid} && renice +10 -p ${pid}`;
   }
 
-  cpx.exec(command, [], { shell: true }).catch((err: unknown) => {
+  cpx.spawn(command, [], { shell: true }).catch((err: unknown) => {
     // eslint-disable-next-line no-console
     console.warn(
       "Failed to configure CPU affinity/priority:",