@simplysm/sd-cli 14.0.30 → 14.0.33

package/tests/utils/angular-build.spec.ts

@@ -1,31 +1,28 @@
 import { describe, it, expect, beforeAll } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
+import * as angularBuildMod from "../../src/angular/angular-build";
 
 describe("Angular Build Adapter - Library Compilation API", () => {
   // Rule: 어댑터는 Library 빌드에 필요한 Angular 컴파일러 API를 노출한다
 
-  it("exports NgtscProgram from adapter module", async () => {
-    const { NgtscProgram } = await import("../../src/utils/angular-build");
-    expect(typeof NgtscProgram).toBe("function");
+  it("exports NgtscProgram from adapter module", () => {
+    expect(typeof angularBuildMod.NgtscProgram).toBe("function");
   });
 
-  it("exports OptimizeFor enum from adapter module", async () => {
-    const { OptimizeFor } = await import("../../src/utils/angular-build");
-    expect(OptimizeFor.WholeProgram).toBeDefined();
-    expect(OptimizeFor.SingleFile).toBeDefined();
+  it("exports OptimizeFor enum from adapter module", () => {
+    expect(angularBuildMod.OptimizeFor.WholeProgram).toBeDefined();
+    expect(angularBuildMod.OptimizeFor.SingleFile).toBeDefined();
   });
 
-  it("NgtscProgram이 AngularLibraryHostExtensions로 확장된 ts.CompilerHost를 수용", async () => {
-    const mod = await import("../../src/utils/angular-build");
-    expect(typeof mod.NgtscProgram).toBe("function");
+  it("NgtscProgram이 AngularLibraryHostExtensions로 확장된 ts.CompilerHost를 수용", () => {
+    expect(typeof angularBuildMod.NgtscProgram).toBe("function");
   });
 });
 
 describe("Angular Build Adapter - Scope after Feature 3.1", () => {
-  it("adapter only exports Library-path APIs (NgtscProgram, OptimizeFor)", async () => {
-    const mod = await import("../../src/utils/angular-build");
-    const exports = Object.keys(mod);
+  it("adapter only exports Library-path APIs (NgtscProgram, OptimizeFor)", () => {
+    const exports = Object.keys(angularBuildMod);
 
     // Library-path exports retained
     expect(exports).toContain("NgtscProgram");
@@ -42,17 +39,15 @@ describe("Angular Build Adapter - Scope after Feature 3.1", () => {
     expect(exports).not.toContain("emitFilesToDisk");
   });
 
-  it("adapter does not export browserslist/PostCSS APIs", async () => {
-    const mod = await import("../../src/utils/angular-build");
-    const exports = Object.keys(mod);
+  it("adapter does not export browserslist/PostCSS APIs", () => {
+    const exports = Object.keys(angularBuildMod);
     expect(exports).not.toContain("transformSupportedBrowsersToTargets");
     expect(exports).not.toContain("getSupportedBrowsers");
     expect(exports).not.toContain("loadPostcssConfiguration");
   });
 
-  it("adapter does not export ServiceWorker/i18n APIs", async () => {
-    const mod = await import("../../src/utils/angular-build");
-    const exports = Object.keys(mod);
+  it("adapter does not export ServiceWorker/i18n APIs", () => {
+    const exports = Object.keys(angularBuildMod);
     expect(exports).not.toContain("augmentAppWithServiceWorker");
     expect(exports).not.toContain("createI18nOptions");
   });
@@ -60,7 +55,7 @@ describe("Angular Build Adapter - Scope after Feature 3.1", () => {
 
 describe("Angular Build Adapter - Isolation", () => {
   const sdCliSrcDir = path.resolve(import.meta.dirname, "../../src");
-  const adapterFiles = ["angular-build.ts", "vite-angular-plugin.ts"];
+  const adapterFiles = ["angular-build.ts", "vite-angular-plugin.ts", "esbuild-client-config.ts", "esbuild-index-html.ts", "esbuild-pwa.ts"];
   let srcFiles: string[];
 
   beforeAll(() => {

package/tests/utils/angular-compiler-emit.spec.ts

@@ -50,7 +50,7 @@ function createRealTsProgram(
 
 let realProgram: { program: ts.Program; dir: string; rootNames: string[] };
 
-vi.mock("../../src/utils/angular-build", () => {
+vi.mock("../../src/angular/angular-build", () => {
   class NgtscProgram {
     compiler = {
       analyzeAsync: mockAnalyzeAsync,
@@ -79,7 +79,7 @@ vi.mock("../../src/utils/angular-build", () => {
 });
 
 const { AngularCompiler, AngularSourceFileCache } = await import(
-  "../../src/utils/angular-compiler"
+  "../../src/angular/angular-compiler"
 );
 
 // --- Common beforeEach ---

package/tests/utils/angular-compiler.spec.ts

@@ -50,7 +50,7 @@ function createRealTsProgram(
 
 let realProgram: { program: ts.Program; dir: string; rootNames: string[] };
 
-vi.mock("../../src/utils/angular-build", () => {
+vi.mock("../../src/angular/angular-build", () => {
   class NgtscProgram {
     compiler = {
       analyzeAsync: mockAnalyzeAsync,
@@ -79,7 +79,7 @@ vi.mock("../../src/utils/angular-build", () => {
 });
 
 const { AngularCompiler, AngularSourceFileCache } = await import(
-  "../../src/utils/angular-compiler"
+  "../../src/angular/angular-compiler"
 );
 
 // --- Common beforeEach ---

package/tests/utils/angular-source-file-cache.spec.ts

@@ -2,13 +2,13 @@ import { describe, it, expect, vi } from "vitest";
 import ts from "typescript";
 
 // Minimal mock to allow angular-compiler import (it depends on angular-build)
-vi.mock("../../src/utils/angular-build", () => ({
+vi.mock("../../src/angular/angular-build", () => ({
   NgtscProgram: vi.fn(),
   OptimizeFor: { WholeProgram: 0, SingleFile: 1 },
 }));
 
 const { AngularSourceFileCache, augmentHostWithCaching } = await import(
-  "../../src/utils/angular-compiler"
+  "../../src/angular/angular-compiler"
 );
 
 // =============================================================================

package/tests/utils/concurrency.spec.ts

@@ -1,9 +1,8 @@
 import { describe, it, expect } from "vitest";
+import { runWithConcurrency, getMaxConcurrency } from "../../src/utils/concurrency";
 
 describe("runWithConcurrency", () => {
   it("limits concurrent task execution to specified concurrency", async () => {
-    const { runWithConcurrency } = await import("../../src/utils/concurrency");
-
     let activeTasks = 0;
     let maxActiveTasks = 0;
 
@@ -23,8 +22,6 @@ describe("runWithConcurrency", () => {
   });
 
   it("returns all results in order even when individual tasks fail", async () => {
-    const { runWithConcurrency } = await import("../../src/utils/concurrency");
-
     const tasks = [
       () => Promise.resolve("a"),
       () => { throw new Error("fail"); },
@@ -40,15 +37,11 @@ describe("runWithConcurrency", () => {
   });
 
   it("handles empty task list", async () => {
-    const { runWithConcurrency } = await import("../../src/utils/concurrency");
-
     const results = await runWithConcurrency([], 3);
     expect(results).toHaveLength(0);
   });
 
   it("works when concurrency exceeds task count", async () => {
-    const { runWithConcurrency } = await import("../../src/utils/concurrency");
-
     const tasks = [() => Promise.resolve(1), () => Promise.resolve(2)];
     const results = await runWithConcurrency(tasks, 10);
 
@@ -58,8 +51,7 @@ describe("runWithConcurrency", () => {
 });
 
 describe("getMaxConcurrency", () => {
-  it("returns at least 1", async () => {
-    const { getMaxConcurrency } = await import("../../src/utils/concurrency");
+  it("returns at least 1", () => {
     expect(getMaxConcurrency()).toBeGreaterThanOrEqual(1);
   });
 });

package/tests/utils/dev-http-server.acc.spec.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "path";
+import os from "node:os";
+import { createDevHttpServer, type DevHttpServer } from "../../src/dev-server/dev-http-server";
+
+describe("createDevHttpServer — Acceptance", () => {
+  let tmpDir: string;
+  let distDir: string;
+  let server: DevHttpServer | undefined;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "dev-http-server-test-"));
+    distDir = path.join(tmpDir, "dist");
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    fs.mkdirSync(distDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (server?.port != null) {
+      await server.close();
+    }
+    server = undefined;
+    fs.rmSync(distDir, { recursive: true, force: true });
+  });
+
+  async function fetchFromServer(urlPath: string): Promise<{
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+  }> {
+    const port = server!.port!;
+    const res = await fetch(`http://127.0.0.1:${port}${urlPath}`);
+    const body = await res.text();
+    const headers: Record<string, string> = {};
+    res.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    return { status: res.status, headers, body };
+  }
+
+  // Scenario: JavaScript 파일 요청
+  it("JavaScript 파일을 올바른 Content-Type으로 서빙한다", async () => {
+    fs.writeFileSync(path.join(distDir, "main.js"), "console.log('hello');");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/main.js");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("javascript");
+    expect(res.body).toBe("console.log('hello');");
+  });
+
+  // Scenario: CSS 파일 요청
+  it("CSS 파일을 올바른 Content-Type으로 서빙한다", async () => {
+    fs.writeFileSync(path.join(distDir, "styles.css"), "body { color: red; }");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/styles.css");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("css");
+  });
+
+  // Scenario: 바이너리 파일 요청
+  it("바이너리 파일을 올바른 Content-Type으로 서빙한다", async () => {
+    fs.mkdirSync(path.join(distDir, "assets"), { recursive: true });
+    // 최소 PNG 파일 (1x1 투명 PNG)
+    const pngBuffer = Uint8Array.from([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
+      0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
+      0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, 0x89, 0x00, 0x00, 0x00,
+      0x0a, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x62, 0x00, 0x00, 0x00, 0x02,
+      0x00, 0x01, 0xe5, 0x27, 0xde, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45,
+      0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+    ]);
+    fs.writeFileSync(path.join(distDir, "assets", "logo.png"), pngBuffer);
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/assets/logo.png");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("image/png");
+  });
+
+  // Scenario: 알 수 없는 확장자 파일 요청
+  it("알 수 없는 확장자 파일은 application/octet-stream으로 서빙한다", async () => {
+    fs.writeFileSync(path.join(distDir, "data.qzx"), "some data");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/data.qzx");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("application/octet-stream");
+  });
+
+  // Scenario: basePath가 없는 요청 → 404
+  it("basePath가 없는 요청은 404를 반환한다", async () => {
+    fs.writeFileSync(path.join(distDir, "main.js"), "console.log('hello');");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/main.js");
+    expect(res.status).toBe(404);
+  });
+
+  // Scenario: 다른 basePath 요청 → 404
+  it("다른 basePath 요청은 404를 반환한다", async () => {
+    fs.writeFileSync(path.join(distDir, "main.js"), "console.log('hello');");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/other-app/main.js");
+    expect(res.status).toBe(404);
+  });
+
+  // Scenario: SPA 라우트 요청 → index.html fallback
+  it("존재하지 않는 경로에 대해 SPA fallback으로 index.html을 반환한다", async () => {
+    fs.writeFileSync(path.join(distDir, "index.html"), "<html><body>SPA</body></html>");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/dashboard/users");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("text/html");
+    expect(res.body).toBe("<html><body>SPA</body></html>");
+  });
+
+  // Scenario: 존재하지 않는 파일 요청 → index.html fallback
+  it("존재하지 않는 파일 요청에 대해 SPA fallback으로 index.html을 반환한다", async () => {
+    fs.writeFileSync(path.join(distDir, "index.html"), "<html><body>SPA</body></html>");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/nonexistent.js");
+    expect(res.status).toBe(200);
+    expect(res.body).toBe("<html><body>SPA</body></html>");
+  });
+
+  // Scenario: index.html도 없는 경우 → 404
+  it("index.html도 없으면 404를 반환한다", async () => {
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/any-path");
+    expect(res.status).toBe(404);
+  });
+
+  // Scenario: 지정 포트로 listen
+  it("지정된 포트로 listen한다", async () => {
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    const port = await server.listen();
+
+    // 자동 할당된 포트로 다시 서버를 만들어 지정 포트 동작 검증
+    await server.close();
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port });
+    const actualPort = await server.listen();
+    expect(actualPort).toBe(port);
+  });
+
+  // Scenario: 자동 포트 할당
+  it("포트 0으로 listen하면 OS가 자동 할당한다", async () => {
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    const port = await server.listen();
+    expect(port).toBeGreaterThan(0);
+  });
+
+  // Scenario: 정적 파일 응답에 Cache-Control 헤더가 포함된다
+  it("JS 파일 응답에 Cache-Control: no-cache 헤더가 포함된다", async () => {
+    fs.writeFileSync(path.join(distDir, "main.js"), "var x = 1;");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/main.js");
+    expect(res.status).toBe(200);
+    expect(res.headers["cache-control"]).toBe("no-cache");
+  });
+
+  // Scenario: SPA fallback 응답에 Cache-Control 헤더가 포함된다
+  it("SPA fallback index.html 응답에 Cache-Control: no-cache 헤더가 포함된다", async () => {
+    fs.writeFileSync(path.join(distDir, "index.html"), "<html>spa</html>");
+
+    server = createDevHttpServer({ distDir, basePath: "/my-app/", port: 0 });
+    await server.listen();
+
+    const res = await fetchFromServer("/my-app/nonexistent-route");
+    expect(res.status).toBe(200);
+    expect(res.headers["cache-control"]).toBe("no-cache");
+  });
+});

package/tests/utils/dev-http-server.spec.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeAll, afterAll, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "path";
+import os from "node:os";
+import { createDevHttpServer, type DevHttpServer } from "../../src/dev-server/dev-http-server";
+
+describe("createDevHttpServer", () => {
+  let tmpDir: string;
+  let distDir: string;
+  let server: DevHttpServer | undefined;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "dev-http-server-unit-"));
+    distDir = path.join(tmpDir, "dist");
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    fs.mkdirSync(distDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (server?.port != null) {
+      await server.close();
+    }
+    fs.rmSync(distDir, { recursive: true, force: true });
+  });
+
+  async function fetchFromServer(urlPath: string): Promise<{
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+  }> {
+    const port = server!.port!;
+    const res = await fetch(`http://127.0.0.1:${port}${urlPath}`);
+    const body = await res.text();
+    const headers: Record<string, string> = {};
+    res.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    return { status: res.status, headers, body };
+  }
+
+  describe("정적 파일 서빙", () => {
+    it("HTML 파일을 text/html로 서빙한다", async () => {
+      fs.writeFileSync(path.join(distDir, "page.html"), "<html>test</html>");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/page.html");
+      expect(res.status).toBe(200);
+      expect(res.headers["content-type"]).toContain("text/html");
+      expect(res.body).toBe("<html>test</html>");
+    });
+
+    it("루트 경로(/) 요청 시 index.html을 서빙한다", async () => {
+      fs.writeFileSync(path.join(distDir, "index.html"), "<html>index</html>");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/");
+      expect(res.status).toBe(200);
+      expect(res.body).toBe("<html>index</html>");
+    });
+
+    it("빈 경로 요청 시 index.html을 서빙한다", async () => {
+      fs.writeFileSync(path.join(distDir, "index.html"), "<html>index</html>");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      // /app (슬래시 없음) — basePath 매칭 후 빈 경로
+      const res = await fetchFromServer("/app/");
+      expect(res.status).toBe(200);
+      expect(res.body).toBe("<html>index</html>");
+    });
+
+    it("하위 디렉토리의 파일을 서빙한다", async () => {
+      fs.mkdirSync(path.join(distDir, "sub"), { recursive: true });
+      fs.writeFileSync(path.join(distDir, "sub", "file.txt"), "content");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/sub/file.txt");
+      expect(res.status).toBe(200);
+      expect(res.body).toBe("content");
+    });
+
+    it("query string이 포함된 요청을 정상 처리한다", async () => {
+      fs.writeFileSync(path.join(distDir, "main.js"), "var x = 1;");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/main.js?v=123");
+      expect(res.status).toBe(200);
+      expect(res.body).toBe("var x = 1;");
+    });
+
+    it("디렉토리 경로 요청 시 SPA fallback으로 index.html 반환", async () => {
+      fs.writeFileSync(path.join(distDir, "index.html"), "<html>spa</html>");
+      fs.mkdirSync(path.join(distDir, "subdir"), { recursive: true });
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/subdir");
+      expect(res.status).toBe(200);
+      expect(res.body).toBe("<html>spa</html>");
+    });
+  });
+
+  describe("Cache-Control 헤더", () => {
+    it("CSS 파일 응답에 Cache-Control: no-cache가 포함된다", async () => {
+      fs.writeFileSync(path.join(distDir, "styles.css"), "body{}");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/styles.css");
+      expect(res.headers["cache-control"]).toBe("no-cache");
+    });
+
+    it("루트 경로 index.html 응답에 Cache-Control: no-cache가 포함된다", async () => {
+      fs.writeFileSync(path.join(distDir, "index.html"), "<html></html>");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      const res = await fetchFromServer("/app/");
+      expect(res.headers["cache-control"]).toBe("no-cache");
+    });
+  });
+
+  describe("httpServer 인스턴스 노출", () => {
+    it("httpServer 프로퍼티를 통해 http.Server 인스턴스에 접근 가능하다", () => {
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      expect(server.httpServer).toBeDefined();
+      expect(typeof server.httpServer.address).toBe("function");
+    });
+  });
+
+  describe("에러 핸들링", () => {
+    it("stat에서 ENOENT가 아닌 에러 발생 시 500을 반환한다", async () => {
+      fs.writeFileSync(path.join(distDir, "index.html"), "<html>spa</html>");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      await server.listen();
+
+      // stat을 spyOn하여 EACCES 에러 시뮬레이션
+      const statSpy = vi.spyOn(fs.promises, "stat").mockRejectedValueOnce(
+        Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }),
+      );
+
+      const res = await fetchFromServer("/app/main.js");
+      expect(res.status).toBe(500);
+
+      statSpy.mockRestore();
+    });
+  });
+
+  describe("close", () => {
+    it("close 후 서버가 더 이상 요청을 받지 않는다", async () => {
+      fs.writeFileSync(path.join(distDir, "main.js"), "test");
+
+      server = createDevHttpServer({ distDir, basePath: "/app/", port: 0 });
+      const port = await server.listen();
+      await server.close();
+
+      await expect(
+        fetch(`http://127.0.0.1:${port}/app/main.js`),
+      ).rejects.toThrow();
+    });
+  });
+});

package/tests/utils/dev-http-server.verify.md

@@ -0,0 +1,8 @@
+# Slice 2: 포트/설정 파일 기록 — LLM 검증
+
+## 검증 항목
+
+- [x] `.dev-port` 파일 기록 패턴 유지: 기존 `client.worker.ts:246,319`에서 `fs.writeFileSync(path.join(distDir, ".dev-port"), String(port))` 패턴을 사용 중이며, 이 패턴은 호출자(worker/engine)에서 동일하게 사용 가능. `createDevHttpServer`의 `listen()` 반환값(port)을 사용하여 기록 가능.
+- [x] `.config.json` 기록 패턴 유지: 기존 `client.worker.ts:439-448`의 `writeConfigJson` 함수가 `fs.mkdirSync + fs.writeFileSync(JSON.stringify)` 패턴으로 구현되어 있으며, Feature 3.1(EsbuildClientEngine)에서 동일하게 호출 가능.
+- [x] configs 미설정 시 빈 객체: 기존 `writeConfigJson`에서 `configs ?? {}`로 처리 (`client.worker.ts:445`). 이 패턴은 호출자가 그대로 유지.
+- [x] 파일 기록 책임 분리: `createDevHttpServer`는 HTTP 서빙에만 집중하고, `.dev-port`/`.config.json` 기록은 호출자 책임 (설계 결정 D3 준수).

package/tests/utils/diagnostic-utils.spec.ts

@@ -1,5 +1,10 @@
+import ts from "typescript";
 import { describe, it, expect } from "vitest";
-import { isWorkspaceDiagnostic, formatDiagnosticError } from "../../src/utils/diagnostic-utils";
+import {
+  isWorkspaceDiagnostic,
+  formatDiagnosticError,
+  formatDiagnosticsOutput,
+} from "../../src/utils/diagnostic-utils";
 
 describe("isWorkspaceDiagnostic", () => {
   it("includes diagnostic when file is within cwd", () => {
@@ -70,3 +75,39 @@ describe("formatDiagnosticError", () => {
     expect(result).toBe("TS1001: Global error");
   });
 });
+
+describe("formatDiagnosticsOutput", () => {
+  it("returns empty string for empty diagnostics array", () => {
+    const result = formatDiagnosticsOutput([], "/workspace");
+    expect(result).toBe("");
+  });
+
+  it("returns formatted string for file-less global diagnostic", () => {
+    const diagnostic: ts.Diagnostic = {
+      file: undefined,
+      start: undefined,
+      length: undefined,
+      messageText: "Global error message",
+      category: ts.DiagnosticCategory.Error,
+      code: 9999,
+    };
+    const result = formatDiagnosticsOutput([diagnostic], "/workspace");
+    expect(result).toContain("Global error message");
+    expect(result).toContain("9999");
+  });
+
+  it("deduplicates identical diagnostics", () => {
+    const sourceFile = ts.createSourceFile("test.ts", "const x = 1;", ts.ScriptTarget.Latest);
+    const diagnostic: ts.Diagnostic = {
+      file: sourceFile,
+      start: 0,
+      length: 5,
+      messageText: "Duplicate error",
+      category: ts.DiagnosticCategory.Error,
+      code: 1234,
+    };
+    const result = formatDiagnosticsOutput([diagnostic, diagnostic], "/workspace");
+    const occurrences = result.split("Duplicate error").length - 1;
+    expect(occurrences).toBe(1);
+  });
+});

package/tests/utils/engine-stop.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { stopEngineWorker } from "../../src/utils/engine-stop";
+import { stopEngineWorker } from "../../src/runtime/engine-stop";
 
 function createMockWorker() {
   return {