@simplysm/sd-cli 14.0.5 → 14.0.7

package/src/utils/replace-deps.ts

@@ -199,7 +199,7 @@ async function resolveAllReplaceDepEntries(
       try {
         await fs.promises.access(resolvedSourcePath);
       } catch {
-        logger.warn(`Source path does not exist, skipping: ${resolvedSourcePath}`);
+        logger.warn(`소스 경로가 존재하지 않아 건너뜀: ${resolvedSourcePath}`);
         continue;
       }
 
@@ -244,7 +244,7 @@ export async function setupReplaceDeps(
   const logger = consola.withTag("sd:cli:replace-deps");
   let setupCount = 0;
 
-  logger.start("Setting up replace-deps");
+  logger.start("replace-deps 설정 중...");
 
   const entries = await resolveAllReplaceDepEntries(projectRoot, replaceDeps, logger);
 
@@ -255,11 +255,11 @@ export async function setupReplaceDeps(
 
       setupCount += 1;
     } catch (err) {
-      logger.error(`Copy replace failed (${targetName}): ${err instanceof Error ? err.message : err}`);
+      logger.error(`[${targetName}] 복사 실패: ${err instanceof Error ? err.message : err}`);
     }
   }
 
-  logger.success(`Replaced ${setupCount} dependencies`);
+  logger.success(`replace-deps 설정 완료 (${setupCount}개 의존성 교체)`);
 
   // Run postinstall scripts from replaced packages
   for (const { targetName, resolvedSourcePath, actualTargetPath } of entries) {
@@ -269,13 +269,13 @@ export async function setupReplaceDeps(
       const postinstall = pkgJson.scripts?.postinstall as string | undefined;
       if (postinstall == null) continue;
 
-      logger.warn(`Running postinstall script for ${targetName}: ${postinstall}`);
-      logger.start(`Running postinstall for ${targetName}`);
+      logger.warn(`[${targetName}] postinstall 스크립트 실행: ${postinstall}`);
+      logger.start(`[${targetName}] postinstall 실행 중...`);
       await promisify(exec)(postinstall, { cwd: actualTargetPath });
-      logger.success(`postinstall done: ${targetName}`);
+      logger.success(`[${targetName}] postinstall 실행 완료`);
     } catch (err) {
       logger.error(
-        `postinstall failed (${targetName}): ${err instanceof Error ? err.message : err}`,
+        `[${targetName}] postinstall 실패: ${err instanceof Error ? err.message : err}`,
       );
     }
   }
@@ -305,7 +305,7 @@ export async function watchReplaceDeps(
   const watchers: FsWatcher[] = [];
   const watchedSources = new Set<string>();
 
-  logger.start(`Watching ${entries.length} replace-deps target(s)`);
+  logger.start(`replace-deps 워치 시작 중... (${entries.length}개 대상)`);
 
   for (const entry of entries) {
     if (watchedSources.has(entry.resolvedSourcePath)) continue;
@@ -359,7 +359,7 @@ export async function watchReplaceDeps(
             }
           } catch (err) {
             logger.error(
-              `Copy failed (${e.targetName}/${relativePath}): ${err instanceof Error ? err.message : err}`,
+              `[${e.targetName}] 복사 실패 (${relativePath}): ${err instanceof Error ? err.message : err}`,
             );
           }
         }
@@ -369,7 +369,7 @@ export async function watchReplaceDeps(
     watchers.push(watcher);
   }
 
-  logger.success(`Replace-deps watch ready`);
+  logger.success("replace-deps 워치 준비 완료");
 
   return {
     entries,

package/src/utils/vite-config.ts

@@ -82,10 +82,9 @@ export async function createClientViteConfig(
         : [options.browserslist]
       : undefined;
 
-  // define: 환경변수 주입
+  // define: 환경변수 주입 (import.meta.env.KEY → Vite가 bare import.meta.env 객체를 자동 구성)
   const define: Record<string, string> = {};
   if (options.env != null) {
-    define["process.env"] = JSON.stringify(options.env);
     for (const [key, value] of Object.entries(options.env)) {
       define[`import.meta.env.${key}`] = JSON.stringify(value);
     }

package/src/utils/worker-utils.ts

@@ -33,7 +33,7 @@ export function registerCleanupHandlers(
         process.exit(0);
       })
       .catch((err) => {
-        logger.error("cleanup failed", err);
+        logger.error("정리 작업 실패", err);
         process.exit(1);
       });
   };

package/src/workers/server-build.worker.ts

@@ -142,7 +142,7 @@ async function cleanup(): Promise<void> {
  * Uses single-pass dependency tree traversal via collectAllDependencyExternals.
  */
 function collectAllExternals(pkgDir: string, manualExternals?: string[]): string[] {
-  logger.debug("[externals] Scanning dependency tree (single pass)...");
+  logger.debug("의존성 트리 스캔 중...");
   const { optionalPeerDeps, nativeModules } = collectAllDependencyExternals(pkgDir);
 
   const manual = manualExternals ?? [];
@@ -638,7 +638,7 @@ async function startWatch(info: ServerWatchInfo): Promise<void> {
           const result = await rebuildAll();
           sender.send("build", result);
         } else {
-          logger.debug("Changed files not included in build, skipping rebuild");
+          logger.debug("변경된 파일이 빌드에 포함되지 않아 리빌드 건너뜀");
         }
       } catch (err) {
         sender.send("error", { message: errNs.message(err) });

package/src/workers/server-runtime.worker.ts

@@ -63,7 +63,7 @@ async function cleanup(): Promise<void> {
 // Catch runtime errors that occur after server listen() and send them as a custom "error" event
 // (Without this handler, the worker will crash but dev.ts's buildResolver won't be called, causing listr to hang)
 process.on("uncaughtException", (err) => {
-  logger.error("Unhandled server runtime error", err);
+  logger.error("서버 런타임 미처리 에러", err);
   sender.send("error", {
     message: errNs.message(err),
   });
@@ -72,7 +72,7 @@ process.on("uncaughtException", (err) => {
 });
 
 process.on("unhandledRejection", (reason) => {
-  logger.error("Unhandled server runtime promise rejection", reason);
+  logger.error("서버 런타임 미처리 Promise 거부", reason);
   sender.send("error", {
     message: errNs.message(reason),
   });
@@ -127,10 +127,10 @@ async function start(info: ServerRuntimeStartInfo): Promise<void> {
     }
 
     // Import main.js (must export a server instance)
-    logger.debug("[start] Importing main.js...");
+    logger.debug("main.js 임포트 중...");
     let stepStart = performance.now();
     const module = await import(pathToFileURL(info.mainJsPath).href);
-    logger.debug(`[start] main.js imported (${Math.round(performance.now() - stepStart)}ms)`);
+    logger.debug(`main.js 임포트 완료 (${Math.round(performance.now() - stepStart)}ms)`);
     const server = module.server;
 
     if (server == null) {
@@ -143,7 +143,7 @@ async function start(info: ServerRuntimeStartInfo): Promise<void> {
     // Register client proxies (before listen)
     if (info.clientPorts != null && Object.keys(info.clientPorts).length > 0) {
       for (const [name, port] of Object.entries(info.clientPorts)) {
-        logger.debug(`[start] Registering proxy: /${name} -> http://127.0.0.1:${String(port)}`);
+        logger.debug(`프록시 등록: /${name} → http://127.0.0.1:${String(port)}`);
         await server.fastify.register(proxy, {
           prefix: `/${name}`,
           upstream: `http://127.0.0.1:${port}`,
@@ -154,31 +154,31 @@ async function start(info: ServerRuntimeStartInfo): Promise<void> {
     }
 
     // Find available port (auto-increment on port conflict)
-    logger.debug("[start] Finding available port...");
+    logger.debug("사용 가능한 포트 탐색 중...");
     stepStart = performance.now();
     const originalPort = server.options.port;
     const availablePort = await findAvailablePort(originalPort);
     if (availablePort !== originalPort) {
-      logger.info(`Port ${originalPort} in use, changing to ${availablePort}`);
+      logger.info(`포트 ${originalPort} 사용 중, ${availablePort}로 변경`);
       server.options.port = availablePort;
     }
     logger.debug(
-      `[start] Port ${String(availablePort)} available (${Math.round(performance.now() - stepStart)}ms)`,
+      `포트 ${String(availablePort)} 사용 가능 (${Math.round(performance.now() - stepStart)}ms)`,
     );
 
-    // Start server
-    logger.debug("[start] Starting server listen...");
+    // 서버 시작
+    logger.debug("서버 리슨 시작...");
     stepStart = performance.now();
     await server.listen();
-    logger.debug(`[start] Server listening (${Math.round(performance.now() - stepStart)}ms)`);
+    logger.debug(`서버 리슨 완료 (${Math.round(performance.now() - stepStart)}ms)`);
 
     logger.debug(
-      `[start] Total runtime startup: ${Math.round(performance.now() - startTime)}ms`,
+      `런타임 총 시작 시간: ${Math.round(performance.now() - startTime)}ms`,
     );
 
     sender.send("serverReady", { port: server.options.port });
   } catch (err) {
-    logger.error("Server Runtime startup failed", err);
+    logger.error("서버 런타임 시작 실패", err);
     sender.send("error", {
       message: errNs.message(err),
     });

package/tests/commands/check.spec.ts

@@ -117,21 +117,20 @@ describe("runCheck", () => {
     writeSpy.mockRestore();
   });
 
-  it("runs typecheck+lint and test, outputs ALL PASSED", async () => {
+  it("runs typecheck+lint and test", async () => {
     await runCheck({ targets: [], types: ["typecheck", "lint", "test"], fix: false });
 
     expect(mocks.executeTypecheck).toHaveBeenCalled();
     expect(mocks.execa).toHaveBeenCalled();
-    expect(stdoutOutput).toContain("ALL PASSED");
   });
 
-  it("outputs results in TYPECHECK → LINT → TEST → SUMMARY order", async () => {
+  it("outputs results in TYPECHECK → LINT → TEST → 요약 order", async () => {
     await runCheck({ targets: [], types: ["typecheck", "lint", "test"], fix: false });
 
     const tcIdx = stdoutOutput.indexOf("TYPECHECK");
     const lintIdx = stdoutOutput.indexOf("LINT");
     const testIdx = stdoutOutput.indexOf("TEST");
-    const summaryIdx = stdoutOutput.indexOf("SUMMARY");
+    const summaryIdx = stdoutOutput.indexOf("요약");
 
     expect(tcIdx).toBeLessThan(lintIdx);
     expect(lintIdx).toBeLessThan(testIdx);
@@ -146,7 +145,7 @@ describe("runCheck", () => {
     expect(mocks.execa).toHaveBeenCalled();
   });
 
-  it("outputs FAILED with failing check names when some fail", async () => {
+  it("sets exitCode 1 when typecheck fails", async () => {
     mocks.executeTypecheck.mockResolvedValue({
       success: false, errorCount: 2, warningCount: 0, formattedOutput: "type errors",
       lint: { success: true, errorCount: 0, warningCount: 0, formattedOutput: "" },
@@ -155,8 +154,6 @@ describe("runCheck", () => {
 
     await runCheck({ targets: [], types: ["typecheck", "lint", "test"], fix: false });
 
-    expect(stdoutOutput).toContain("FAILED");
-    expect(stdoutOutput).toContain("typecheck");
     expect(process.exitCode).toBe(1);
   });
 
@@ -170,14 +167,13 @@ describe("runCheck", () => {
     expect(process.exitCode).toBe(1);
   });
 
-  it("parses test failure count from vitest output", async () => {
+  it("sets exitCode 1 when test fails", async () => {
     mocks.execa.mockResolvedValue({
       stdout: "3 tests failed", stderr: "", exitCode: 1,
     });
 
     await runCheck({ targets: [], types: ["test"], fix: false });
 
-    expect(stdoutOutput).toContain("3 failed");
     expect(process.exitCode).toBe(1);
   });
 
@@ -271,8 +267,8 @@ describe("runCheck", () => {
       expect(mocks.runLintInWorker).not.toHaveBeenCalled();
     });
 
-    // Scenario: check 결과 출력에 LINT 섹션이 포함된다
-    it("outputs separate TYPECHECK and LINT sections from engine results", async () => {
+    // Scenario: lint 실패 시 exitCode 설정
+    it("sets exitCode 1 when engine lint fails", async () => {
       mocks.executeTypecheck.mockResolvedValue({
         success: true, errorCount: 0, warningCount: 0, formattedOutput: "",
         lint: { success: false, errorCount: 3, warningCount: 1, formattedOutput: "some lint output" },
@@ -281,10 +277,7 @@ describe("runCheck", () => {
 
       await runCheck({ targets: [], types: ["typecheck", "lint"], fix: false });
 
-      expect(stdoutOutput).toContain("TYPECHECK");
-      expect(stdoutOutput).toContain("LINT");
-      expect(stdoutOutput).toContain("3 errors");
-      expect(stdoutOutput).toContain("1 warnings");
+      expect(process.exitCode).toBe(1);
     });
 
     // Scenario: check에서 scripts 패키지의 lint가 별도 실행된다
@@ -391,43 +384,35 @@ describe("runCheck", () => {
     });
 
     // Scenario: lint 에러 없음
-    it("outputs ALL PASSED when lint has no errors", async () => {
+    it("does not set exitCode when lint passes", async () => {
       mocks.executeLint.mockResolvedValue({
         success: true, errorCount: 0, warningCount: 0, formattedOutput: "",
       });
 
       await runCheck({ targets: [], types: ["lint"], fix: false });
 
-      expect(stdoutOutput).toContain("LINT");
-      expect(stdoutOutput).toContain("✔ 0 errors, 0 warnings");
-      expect(stdoutOutput).toContain("✔ ALL PASSED");
       expect(process.exitCode).toBeUndefined();
     });
 
     // Scenario: lint 에러 발생
-    it("outputs FAILED when lint has errors", async () => {
+    it("sets exitCode 1 when lint has errors", async () => {
       mocks.executeLint.mockResolvedValue({
         success: false, errorCount: 3, warningCount: 2, formattedOutput: "lint errors",
       });
 
       await runCheck({ targets: [], types: ["lint"], fix: false });
 
-      expect(stdoutOutput).toContain("LINT");
-      expect(stdoutOutput).toContain("✖ 3 errors, 2 warnings");
-      expect(stdoutOutput).toContain("✖ 1/1 FAILED (lint)");
       expect(process.exitCode).toBe(1);
     });
 
     // Scenario: lint 대상 파일 없음
-    it("outputs ALL PASSED when no files to lint", async () => {
+    it("does not set exitCode when no files to lint", async () => {
       mocks.executeLint.mockResolvedValue({
         success: true, errorCount: 0, warningCount: 0, formattedOutput: "",
       });
 
       await runCheck({ targets: [], types: ["lint"], fix: false });
 
-      expect(stdoutOutput).toContain("✔ 0 errors, 0 warnings");
-      expect(stdoutOutput).toContain("✔ ALL PASSED");
       expect(process.exitCode).toBeUndefined();
     });
 

package/tests/electron/electron.spec.ts

@@ -278,6 +278,25 @@ describe("Electron", () => {
 
       await expect(electron.build("/fake/out")).rejects.toThrow("electron-main.ts");
     });
+
+    it("config.env를 esbuild banner로 주입한다 (ELECTRON_DEV_URL 미포함)", async () => {
+      const { Electron } = await import("../../src/electron/electron.js");
+
+      const electron = await Electron.create(PKG_PATH, {
+        appId: "com.test.app",
+        env: { API_URL: "https://api.example.com" },
+      });
+      await electron.build("/fake/out");
+
+      const callArgs = mockEsbuildBuild.mock.calls[0][0];
+      const banner = callArgs.banner?.js as string;
+      expect(banner).toContain("process.env");
+      expect(banner).toContain("??=");
+      expect(banner).toContain("API_URL");
+      expect(banner).toContain("https://api.example.com");
+      expect(banner).not.toContain("ELECTRON_DEV_URL");
+      expect(callArgs.define).toBeUndefined();
+    });
   });
 
   //#endregion
@@ -440,7 +459,7 @@ describe("Electron", () => {
       return { electronKill, resolveElectron: () => resolveElectron() };
     }
 
-    it("creates esbuild context and spawns Electron on build success", async () => {
+    it("creates esbuild context with banner for env and spawns Electron", async () => {
       const { resolveElectron } = setupExecaForRun();
 
       const { Electron } = await import("../../src/electron/electron.js");
@@ -455,28 +474,20 @@ describe("Electron", () => {
       resolveElectron();
       await runPromise;
 
-      // esbuild.context was called
-      expect(mockEsbuildContext).toHaveBeenCalledWith(
-        expect.objectContaining({
-          platform: "node",
-          target: "node20",
-          format: "cjs",
-          bundle: true,
-          external: expect.arrayContaining(["electron"]),
-        }),
-      );
-
-      // Electron was spawned via execa
-      const electronCall = mockExeca.mock.calls.find(
-        (c: any[]) => typeof c[0] === "string" && c[0].includes("electron"),
-      );
-      expect(electronCall).toBeDefined();
-      expect(electronCall![2].env).toEqual(
-        expect.objectContaining({
-          NODE_ENV: "development",
-          ELECTRON_DEV_URL: "http://localhost:4200",
-        }),
-      );
+      // esbuild.context was called with banner containing ELECTRON_DEV_URL
+      const callArgs = mockEsbuildContext.mock.calls[0][0];
+      const banner = callArgs.banner?.js as string;
+      expect(banner).toContain("process.env");
+      expect(banner).toContain("??=");
+      expect(banner).toContain("ELECTRON_DEV_URL");
+      expect(banner).toContain("http://localhost:4200");
+      expect(callArgs.define).toBeUndefined();
+
+      expect(callArgs.platform).toBe("node");
+      expect(callArgs.target).toBe("node20");
+      expect(callArgs.format).toBe("cjs");
+      expect(callArgs.bundle).toBe(true);
+      expect(callArgs.external).toContain("electron");
     }, 10_000);
 
     it("throws when electron-main.ts entry point is missing", async () => {
@@ -513,7 +524,7 @@ describe("Electron", () => {
   });
 
   describe("단위: run() 플러그인 동작", () => {
-    it("passes custom env and ELECTRON_DEV_URL to spawned Electron process", async () => {
+    it("passes custom env and ELECTRON_DEV_URL via esbuild banner", async () => {
       let resolveElectron: () => void = () => {};
       mockExeca.mockImplementation((cmd: string) => {
         if (typeof cmd === "string" && cmd.includes("electron")) {
@@ -537,17 +548,13 @@ describe("Electron", () => {
       resolveElectron();
       await runPromise;
 
-      const execaCall = mockExeca.mock.calls.find(
-        (c: any[]) => typeof c[0] === "string" && c[0].includes("electron"),
-      );
-      expect(execaCall).toBeDefined();
-      expect(execaCall![2].env).toEqual(
-        expect.objectContaining({
-          NODE_ENV: "development",
-          ELECTRON_DEV_URL: "http://localhost:5555",
-          CUSTOM_VAR: "test-value",
-        }),
-      );
+      const callArgs = mockEsbuildContext.mock.calls[0][0];
+      const banner = callArgs.banner?.js as string;
+      expect(banner).toContain("ELECTRON_DEV_URL");
+      expect(banner).toContain("http://localhost:5555");
+      expect(banner).toContain("CUSTOM_VAR");
+      expect(banner).toContain("test-value");
+      expect(callArgs.define).toBeUndefined();
     }, 10_000);
 
     it("calls initialize() before starting esbuild context", async () => {

package/tests/orchestrators/build-orchestrator.spec.ts

@@ -221,7 +221,7 @@ describe("BuildOrchestrator.initialize", () => {
     );
   });
 
-  it("outputs message when no packages to build", async () => {
+  it("returns false when only scripts packages exist", async () => {
     setupDefaults({
       packages: {
         "sd-claude": { target: "scripts" } as any,
@@ -230,10 +230,9 @@ describe("BuildOrchestrator.initialize", () => {
 
     const orchestrator = new BuildOrchestrator({ targets: [], options: [] });
     await orchestrator.initialize();
+    const hasError = await orchestrator.start();
 
-    expect(process.stdout.write).toHaveBeenCalledWith(
-      expect.stringContaining("No packages to build"),
-    );
+    expect(hasError).toBe(false);
   });
 });
 
@@ -403,10 +402,9 @@ describe("BuildOrchestrator.start", () => {
     const hasError = await orchestrator.start();
 
     expect(hasError).toBe(false);
-    expect(mockLogger.info).toHaveBeenCalledWith("Build completed");
   });
 
-  it("returns true and logs error when any build fails", async () => {
+  it("returns true when any build fails", async () => {
     setupDefaults({
       packages: {
         "core-common": { target: "neutral", publish: { type: "npm" } },
@@ -429,7 +427,6 @@ describe("BuildOrchestrator.start", () => {
     const hasError = await orchestrator.start();
 
     expect(hasError).toBe(true);
-    expect(mockLogger.error).toHaveBeenCalledWith("Build failed");
   });
 
   it("returns false when no packages to build", async () => {
@@ -658,7 +655,6 @@ describe("BuildOrchestrator client build", () => {
     const hasError = await orchestrator.start();
 
     expect(hasError).toBe(true);
-    expect(mockLogger.error).toHaveBeenCalledWith("Build failed");
   });
 
   // Acceptance: Scenario "BuildOrchestrator가 env를 ViteEngine에 전달" + "프로덕션 빌드의 baseEnv"
@@ -1049,7 +1045,6 @@ describe("BuildOrchestrator lint integration", () => {
     const hasError = await orchestrator.start();
 
     expect(hasError).toBe(true);
-    expect(mockLogger.error).toHaveBeenCalledWith("Build failed");
   });
 
   // Scenario: build에서 scripts 패키지는 제외된다

package/tests/orchestrators/dev-watch-orchestrator.spec.ts

@@ -300,7 +300,6 @@ describe("DevWatchOrchestrator", () => {
       const orchestrator = new DevWatchOrchestrator({ mode: "watch", targets: [], options: [] });
       await orchestrator.initialize();
 
-      expect(process.stdout.write).toHaveBeenCalledWith(expect.stringContaining("No packages"));
       expect(createBuildEngine).not.toHaveBeenCalled();
     });
 
@@ -872,7 +871,6 @@ describe("DevWatchOrchestrator", () => {
 
       expect(mockBuildEngines[0].stop).toHaveBeenCalledOnce();
       expect(mockRuntimeProxies[0].terminate).toHaveBeenCalled();
-      expect(process.stdout.write).toHaveBeenCalledWith(expect.stringContaining("Shutting down"));
     });
 
     // --- Acceptance: dev에서 replaceDeps 감시 ---
@@ -890,8 +888,8 @@ describe("DevWatchOrchestrator", () => {
       expect(watchReplaceDeps).toHaveBeenCalledWith("/test-root", replaceDeps);
     });
 
-    // Unit: outputs warning when no server packages
-    it("outputs warning when no server packages in dev mode", async () => {
+    // Unit: no server packages in dev mode — does not create runtime proxies
+    it("does not create runtime proxies when no server packages in dev mode", async () => {
       setupDefaults(createConfig({
         packages: { "core-common": { target: "node" } },
       }));
@@ -899,7 +897,7 @@ describe("DevWatchOrchestrator", () => {
       const orchestrator = new DevWatchOrchestrator({ mode: "dev", targets: [], options: [] });
       await orchestrator.initialize();
 
-      expect(process.stdout.write).toHaveBeenCalledWith(expect.stringContaining("No"));
+      expect(createBuildEngine).not.toHaveBeenCalled();
     });
 
     // Unit: multiple server packages

package/tests/utils/esbuild-config.spec.ts

@@ -17,7 +17,7 @@ vi.mock("consola", () => ({
   },
 }));
 
-const { createServerEsbuildOptions, writeChangedOutputFiles } =
+const { createServerEsbuildOptions, createEnvBanner, writeChangedOutputFiles } =
   await import("../../src/utils/esbuild-config");
 
 const { default: mockFs } = await import("fs/promises");
@@ -53,20 +53,25 @@ describe("createServerEsbuildOptions", () => {
     expect((result.banner as Record<string, string>)["js"]).toContain("import.meta.url");
   });
 
-  it("substitutes env vars via define (process.env.KEY → constant)", () => {
+  it("injects env vars via banner (process.env merge) instead of define", () => {
     const result = createServerEsbuildOptions({
       ...baseOptions,
       env: { API_URL: "https://api.example.com", NODE_ENV: "production" },
     });
-    expect(result.define).toEqual({
-      "process.env.API_URL": '"https://api.example.com"',
-      "process.env.NODE_ENV": '"production"',
-    });
+    const banner = (result.banner as Record<string, string>)["js"];
+    expect(banner).toContain("process.env");
+    expect(banner).toContain("??=");
+    expect(banner).toContain("API_URL");
+    expect(banner).toContain("https://api.example.com");
+    expect(result.define).toBeUndefined();
   });
 
-  it("produces empty define when env is not provided", () => {
+  it("does not include env code in banner when env is not provided", () => {
     const result = createServerEsbuildOptions(baseOptions);
-    expect(result.define).toEqual({});
+    const banner = (result.banner as Record<string, string>)["js"];
+    expect(banner).toContain("createRequire");
+    expect(banner).not.toContain("??=");
+    expect(result.define).toBeUndefined();
   });
 
   it("passes external modules to esbuild", () => {
@@ -88,6 +93,31 @@ describe("createServerEsbuildOptions", () => {
   });
 });
 
+describe("createEnvBanner", () => {
+  it("generates process.env merge code with ??= for runtime override", () => {
+    const banner = createEnvBanner({ API_URL: "https://api.example.com", NODE_ENV: "production" });
+    expect(banner).toContain("process.env");
+    expect(banner).toContain("??=");
+    expect(banner).toContain('"API_URL"');
+    expect(banner).toContain('"https://api.example.com"');
+    expect(banner).toContain('"NODE_ENV"');
+    expect(banner).toContain('"production"');
+  });
+
+  it("returns empty string when env is undefined", () => {
+    expect(createEnvBanner()).toBe("");
+  });
+
+  it("returns empty string when env is empty object", () => {
+    expect(createEnvBanner({})).toBe("");
+  });
+
+  it("JSON-encodes special characters in values", () => {
+    const banner = createEnvBanner({ MSG: 'hello "world"' });
+    expect(banner).toContain('\\"world\\"');
+  });
+});
+
 describe("writeChangedOutputFiles", () => {
   beforeEach(() => {
     vi.mocked(mockFs.readFile).mockReset();

package/tests/utils/vite-config.spec.ts

@@ -67,6 +67,19 @@ afterEach(() => {
 });
 
 describe("createClientViteConfig", () => {
+  // Acceptance: Scenario "define['process.env'] 제거"
+  it("does not include process.env in define, only import.meta.env keys", async () => {
+    const config = await createClientViteConfig({
+      ...createDefaultOptions(),
+      env: { DEV: "true", VER: "1.0.0" },
+    });
+
+    const define = config.define as Record<string, string>;
+    expect(define).not.toHaveProperty("process.env");
+    expect(define["import.meta.env.DEV"]).toBe('"true"');
+    expect(define["import.meta.env.VER"]).toBe('"1.0.0"');
+  });
+
   // Acceptance: Scenario "browserslist 미설정 시 최신 브라우저 유지"
   it("uses es2022 esbuild target when no browserslist is provided", async () => {
     const config = await createClientViteConfig(createDefaultOptions());