@simplysm/sd-cli 14.0.30 → 14.0.32

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

@@ -1,17 +1,15 @@
 import type ts from "typescript";
 import { createWorker, FsWatcher, pathx } from "@simplysm/core-node";
 import { err as errNs } from "@simplysm/core-common";
-import { consola } from "consola";
 import type { SdBuildPackageConfig } from "../sd-config.types";
 import type { BuildOutput } from "../engines/types";
-import type { SerializedDiagnostic } from "../utils/typecheck-serialization";
-import type { LintWithProgramResult } from "../utils/lint-with-program";
+import type { SerializedDiagnostic } from "../typecheck/typecheck-serialization";
+import type { LintWithProgramResult } from "../lint/lint-with-program";
 import { runTscPackageBuild } from "../utils/tsc-build";
-import { LintWithProgramRunner } from "../utils/lint-with-program";
-import { collectDeps } from "../utils/package-utils";
-import { registerCleanupHandlers, createOnceGuard, setupWorkerConsola } from "../utils/worker-utils";
-
-setupWorkerConsola();
+import { LintWithProgramRunner } from "../lint/lint-with-program";
+import { setupWorkerLifecycle } from "./shared-worker-lifecycle";
+import { buildWatchPaths } from "./build-watch-paths";
+import { hasFileAddOrRemove, shouldSkipRebuild } from "./build-change-filter";
 
 //#region Types
 
@@ -45,8 +43,6 @@ export interface LibraryBuildWorkerEvents extends Record<string, unknown> {
 
 //#region Resource Management
 
-const logger = consola.withTag("sd:cli:library-build:worker");
-
 let fsWatcher: FsWatcher | undefined;
 
 async function cleanup(): Promise<void> {
@@ -57,7 +53,7 @@ async function cleanup(): Promise<void> {
   await watcherToClose?.close();
 }
 
-registerCleanupHandlers(cleanup, logger);
+const { logger, guardStartWatch } = setupWorkerLifecycle("library-build", cleanup);
 
 //#endregion
 
@@ -101,8 +97,6 @@ async function build(info: LibraryBuildInfo): Promise<LibraryBuildResult> {
 
 //#region startWatch (watch mode)
 
-const guardStartWatch = createOnceGuard("startWatch");
-
 // watch 모드용 가변 상태
 let watchInfo: LibraryBuildInfo | undefined;
 let watchLintRunner: LintWithProgramRunner | undefined;
@@ -169,34 +163,21 @@ async function startWatch(info: LibraryBuildInfo): Promise<void> {
     sender.send("build", initialResult);
 
     // workspace 의존성 경로 + replaceDeps 수집
-    const { workspaceDeps, replaceDeps } = collectDeps(info.pkgDir, info.cwd, info.replaceDeps);
+    const { watchPaths } = buildWatchPaths({
+      pkgDir: info.pkgDir,
+      cwd: info.cwd,
+      srcGlobs: ["*.ts"],
+      replaceDeps: info.replaceDeps,
+    });
 
     // FsWatcher 시작 — 자체 src/ + workspace 의존성 src/ + replaceDeps dist/
     logger.debug(`[${info.name}] FsWatcher 시작`);
-    const watchPaths = [
-      pathx.posixResolve(info.pkgDir, "src", "**", "*.ts"),
-      ...workspaceDeps.map((d) => pathx.posixResolve(info.cwd, "packages", d, "src", "**", "*.ts")),
-      ...replaceDeps.flatMap((pkg) => [
-        pathx.posixResolve(info.cwd, "node_modules", ...pkg.split("/"), "dist", "**", "*.{js,mjs,cjs}"),
-        pathx.posixResolve(info.pkgDir, "node_modules", ...pkg.split("/"), "dist", "**", "*.{js,mjs,cjs}"),
-      ]),
-    ];
     fsWatcher = await FsWatcher.watch(watchPaths);
 
     fsWatcher.onChange({ delay: 300 }, async (changes) => {
       try {
-        const hasFileAddOrRemove = changes.some(
-          (c) => c.event === "add" || c.event === "unlink",
-        );
-
-        if (!hasFileAddOrRemove && lastSourceFilePaths != null) {
-          const hasRelevantChange = changes.some((c) =>
-            lastSourceFilePaths!.has(c.path),
-          );
-          if (!hasRelevantChange) {
-            logger.debug("변경된 파일이 빌드에 포함되지 않아 리빌드 건너뜀");
-            return;
-          }
+        if (shouldSkipRebuild(changes.map((c) => c.path), hasFileAddOrRemove(changes), lastSourceFilePaths, logger)) {
+          return;
         }
 
         sender.send("buildStart", {});

package/src/workers/lint.worker.ts

@@ -1,5 +1,5 @@
 import { createWorker } from "@simplysm/core-node";
-import { executeLint, type LintOptions, type LintResult } from "../utils/lint-core";
+import { executeLint, type LintOptions, type LintResult } from "../lint/lint-core";
 
 //#region Worker
 

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

@@ -1,8 +1,9 @@
 import path from "path";
 import { createWorker, FsWatcher, pathx } from "@simplysm/core-node";
 import { err as errNs } from "@simplysm/core-common";
-import { consola } from "consola";
-import { registerCleanupHandlers, createOnceGuard, setupWorkerConsola } from "../utils/worker-utils";
+import { setupWorkerLifecycle } from "./shared-worker-lifecycle";
+import { buildWatchPaths } from "./build-watch-paths";
+import { hasFileAddOrRemove, shouldSkipRebuild } from "./build-change-filter";
 import {
   buildCompilerOptions,
   buildScssLoadPaths,
@@ -12,20 +13,17 @@ import {
   type NgtscBuildResult,
   type NgtscCombinedBuildEvent,
   type SideEffectScssEntry,
-} from "../utils/ngtsc-build-core";
-import { serializeDiagnostic } from "../utils/typecheck-serialization";
-import { LintWithProgramRunner, type LintWithProgramResult } from "../utils/lint-with-program";
+} from "../angular/ngtsc-build-core";
+import { serializeDiagnostic } from "../typecheck/typecheck-serialization";
+import { LintWithProgramRunner, type LintWithProgramResult } from "../lint/lint-with-program";
 import {
   parseTsconfig,
   getPackageSourceFiles,
   getPackageFiles,
   getCompilerOptionsForEnv,
 } from "../utils/tsconfig";
-import { AngularBuildPipeline } from "../utils/angular-build-pipeline";
-import { AngularSourceFileCache } from "../utils/angular-compiler";
-import { collectDeps } from "../utils/package-utils";
-
-setupWorkerConsola();
+import { AngularBuildPipeline } from "../angular/angular-build-pipeline";
+import { AngularSourceFileCache } from "../angular/angular-compiler";
 
 //#region 타입 (워커 인터페이스용 re-export)
 
@@ -41,8 +39,6 @@ export interface NgtscBuildWorkerEvents extends Record<string, unknown> {
 
 //#region Resource Management
 
-const logger = consola.withTag("sd:cli:ngtsc-build:worker");
-
 let fsWatcher: FsWatcher | undefined;
 
 async function cleanup(): Promise<void> {
@@ -56,7 +52,7 @@ async function cleanup(): Promise<void> {
   }
 }
 
-registerCleanupHandlers(cleanup, logger);
+const { logger, guardStartWatch } = setupWorkerLifecycle("ngtsc-build", cleanup);
 
 //#endregion
 
@@ -141,8 +137,6 @@ async function build(info: NgtscBuildInfo): Promise<NgtscBuildResult> {
 
 //#region startWatch (watch mode)
 
-const guardStartWatch = createOnceGuard("startWatch");
-
 let watchInfo: NgtscBuildInfo | undefined;
 let _watchPipeline: AngularBuildPipeline | undefined;
 let watchLintRunner: LintWithProgramRunner | undefined;
@@ -266,36 +260,21 @@ async function startWatch(info: NgtscBuildInfo): Promise<void> {
     sender.send("build", initialResult);
 
     // workspace 의존성 경로 + replaceDeps 수집
-    const { workspaceDeps, replaceDeps } = collectDeps(
-      watchInfo.pkgDir,
-      watchInfo.cwd,
-      watchInfo.replaceDeps,
-    );
+    const { watchPaths } = buildWatchPaths({
+      pkgDir: watchInfo.pkgDir,
+      cwd: watchInfo.cwd,
+      srcGlobs: ["*.{ts,scss,css}"],
+      extraDirs: [{ dir: "scss", globs: ["*.{scss,css}"] }],
+      replaceDeps: watchInfo.replaceDeps,
+    });
 
     // FsWatcher 시작
     logger.debug(`[${watchInfo.name}] FsWatcher 시작`);
-    const watchPaths = [
-      pathx.posixResolve(watchInfo.pkgDir, "src", "**", "*.{ts,scss,css}"),
-      pathx.posixResolve(watchInfo.pkgDir, "scss", "**", "*.{scss,css}"),
-      ...workspaceDeps.flatMap((d) => {
-        const depDir = pathx.posixResolve(watchInfo!.cwd, "packages", d);
-        return [
-          pathx.posixResolve(depDir, "src", "**", "*.{ts,scss,css}"),
-          pathx.posixResolve(depDir, "scss", "**", "*.{scss,css}"),
-        ];
-      }),
-      ...replaceDeps.flatMap((pkg) => [
-        pathx.posixResolve(watchInfo!.cwd, "node_modules", ...pkg.split("/"), "dist", "**", "*.{js,mjs,cjs}"),
-        pathx.posixResolve(watchInfo!.pkgDir, "node_modules", ...pkg.split("/"), "dist", "**", "*.{js,mjs,cjs}"),
-      ]),
-    ];
     fsWatcher = await FsWatcher.watch(watchPaths);
 
     fsWatcher.onChange({ delay: 300 }, async (changedFiles) => {
       try {
-        const hasFileAddOrRemove = changedFiles.some(
-          (c) => c.event === "add" || c.event === "unlink",
-        );
+        const addOrRemove = hasFileAddOrRemove(changedFiles);
 
         // 변경된 파일 수집 (전체 변경 + SCSS 의존성 역방향 탐색)
         const modifiedFiles = new Set<string>();
@@ -311,14 +290,8 @@ async function startWatch(info: NgtscBuildInfo): Promise<void> {
         }
 
         // 의존성 필터: 관련 변경이 없으면 리빌드 건너뜀
-        if (!hasFileAddOrRemove && lastSourceFilePaths != null) {
-          const hasRelevantChange = [...modifiedFiles].some((p) =>
-            lastSourceFilePaths!.has(p),
-          );
-          if (!hasRelevantChange) {
-            logger.debug("변경된 파일이 빌드에 포함되지 않아 리빌드 건너뜀");
-            return;
-          }
+        if (shouldSkipRebuild(modifiedFiles, addOrRemove, lastSourceFilePaths, logger)) {
+          return;
         }
 
         sender.send("buildStart", {});

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

@@ -4,10 +4,9 @@ import fs from "fs";
 import esbuild from "esbuild";
 import { createWorker, FsWatcher, pathx } from "@simplysm/core-node";
 import { err as errNs } from "@simplysm/core-common";
-import { consola } from "consola";
 import type { BuildOutput } from "../engines/types";
-import type { SerializedDiagnostic } from "../utils/typecheck-serialization";
-import type { LintWithProgramResult } from "../utils/lint-with-program";
+import type { SerializedDiagnostic } from "../typecheck/typecheck-serialization";
+import type { LintWithProgramResult } from "../lint/lint-with-program";
 import {
   parseTsconfig,
   getPackageSourceFiles,
@@ -15,13 +14,15 @@ import {
 import {
   createServerEsbuildOptions,
   writeChangedOutputFiles,
-} from "../utils/esbuild-config";
-import { collectAllExternals, generateProductionFiles } from "../utils/server-production-files";
+} from "../esbuild/esbuild-config";
+import { collectAllExternals, generateProductionFiles } from "../deps/server-externals/server-production-files";
 import { runTscPackageBuild } from "../utils/tsc-build";
-import { LintWithProgramRunner } from "../utils/lint-with-program";
-import { registerCleanupHandlers, createOnceGuard, setupWorkerConsola } from "../utils/worker-utils";
-import { collectDeps } from "../utils/package-utils";
+import { LintWithProgramRunner } from "../lint/lint-with-program";
+import { setupWorkerLifecycle } from "./shared-worker-lifecycle";
+import { buildWatchPaths } from "./build-watch-paths";
 import { copyPublicFiles, watchPublicFiles } from "../utils/copy-public";
+import * as esbuildCtx from "./server-esbuild-context";
+import { startServerWatchLoop } from "./server-watch-manager";
 
 //#region Types
 
@@ -97,16 +98,6 @@ export interface ServerBuildWorkerEvents extends Record<string, unknown> {
 
 //#region Resource Management
 
-setupWorkerConsola();
-
-const logger = consola.withTag("sd:cli:server-build:worker");
-
-/** esbuild 빌드 컨텍스트 (정리 대상) */
-let esbuildContext: esbuild.BuildContext | undefined;
-
-/** 마지막 빌드 metafile (리빌드 시 변경 파일 필터링용) */
-let lastMetafile: esbuild.Metafile | undefined;
-
 /** public 파일 감시자 (정리 대상) */
 let publicWatcher: FsWatcher | undefined;
 
@@ -114,9 +105,7 @@ let publicWatcher: FsWatcher | undefined;
 let srcWatcher: FsWatcher | undefined;
 
 async function cleanup(): Promise<void> {
-  const contextToDispose = esbuildContext;
-  esbuildContext = undefined;
-  lastMetafile = undefined;
+  await esbuildCtx.dispose();
   lastBuilderProgram = undefined;
 
   const watcherToClose = publicWatcher;
@@ -125,9 +114,6 @@ async function cleanup(): Promise<void> {
   const srcWatcherToClose = srcWatcher;
   srcWatcher = undefined;
 
-  if (contextToDispose != null) {
-    await contextToDispose.dispose();
-  }
   if (watcherToClose != null) {
     await watcherToClose.close();
   }
@@ -136,7 +122,7 @@ async function cleanup(): Promise<void> {
   }
 }
 
-registerCleanupHandlers(cleanup, logger);
+const { logger, guardStartWatch } = setupWorkerLifecycle("server-build", cleanup);
 
 //#endregion
 
@@ -246,8 +232,6 @@ async function build(info: ServerBuildInfo): Promise<ServerBuildResult> {
   }
 }
 
-const guardStartWatch = createOnceGuard("startWatch");
-
 // watch 모드용 가변 상태
 let watchInfo: ServerWatchInfo | undefined;
 let watchLintRunner: LintWithProgramRunner | undefined;
@@ -263,26 +247,7 @@ async function rebuildAll(): Promise<ServerCombinedBuildEvent> {
   const parsedConfig = parseTsconfig(info.pkgDir);
 
   // esbuild 리빌드 (비동기)
-  let esbuildPromise: Promise<{ success: boolean; errors?: string[]; warnings?: string[] }> | null = null;
-  if (info.output.js && esbuildContext != null) {
-    esbuildPromise = esbuildContext.rebuild().then(async (result) => {
-      // metafile 저장
-      if (result.metafile != null) {
-        lastMetafile = result.metafile;
-      }
-
-      if (result.outputFiles) {
-        await writeChangedOutputFiles(result.outputFiles);
-      }
-      const errors = result.errors.map((e) => e.text);
-      const warnings = result.warnings.map((w) => w.text);
-      return {
-        success: result.errors.length === 0,
-        errors: errors.length > 0 ? errors : undefined,
-        warnings: warnings.length > 0 ? warnings : undefined,
-      };
-    });
-  }
+  const esbuildPromise = info.output.js ? esbuildCtx.rebuild() : null;
 
   // tsc 리빌드 (동기, 증분)
   const tscResult = runTscPackageBuild({
@@ -313,8 +278,8 @@ async function rebuildAll(): Promise<ServerCombinedBuildEvent> {
     logger.debug(`[${info.name}] lint 완료`);
   }
 
-  const jsResult = esbuildPromise
-    ? await esbuildPromise
+  const jsResult = esbuildPromise != null
+    ? (await esbuildPromise) ?? { success: true, errors: undefined, warnings: undefined }
     : { success: true, errors: undefined, warnings: undefined };
 
   const allErrors = [...(jsResult.errors ?? []), ...(tscResult.errors ?? [])];
@@ -330,29 +295,6 @@ async function rebuildAll(): Promise<ServerCombinedBuildEvent> {
   };
 }
 
-/**
- * watch 모드용 esbuild 컨텍스트를 생성한다
- */
-async function createEsbuildWatchContext(
-  info: ServerWatchInfo,
-  entryPoints: string[],
-  external: string[],
-): Promise<esbuild.BuildContext> {
-  const baseOptions = createServerEsbuildOptions({
-    pkgDir: info.pkgDir,
-    entryPoints,
-    env: info.env,
-    external,
-    dev: true,
-  });
-
-  return esbuild.context({
-    ...baseOptions,
-    metafile: true,
-    write: false,
-  });
-}
-
 /**
  * watch 모드 시작
  */
@@ -365,12 +307,17 @@ async function startWatch(info: ServerWatchInfo): Promise<void> {
     const parsedConfig = parseTsconfig(info.pkgDir);
     const entryPoints = getPackageSourceFiles(info.pkgDir, parsedConfig);
 
-    // 외부 모듈 수집 (watch 모드용 캐시)
-    let cachedExternal = collectAllExternals(info.pkgDir, info.externals);
+    // 외부 모듈 수집 (watch 모드용 — watch manager가 자체 캐시를 유지)
+    const cachedExternal = collectAllExternals(info.pkgDir, info.externals);
 
     // esbuild 컨텍스트 생성 (JS 출력 필요 시)
     if (info.output.js) {
-      esbuildContext = await createEsbuildWatchContext(info, entryPoints, cachedExternal);
+      await esbuildCtx.createContext({
+        pkgDir: info.pkgDir,
+        entryPoints,
+        env: info.env,
+        external: cachedExternal,
+      });
     }
 
     // 초기 빌드: esbuild + tsc 병렬
@@ -386,100 +333,23 @@ async function startWatch(info: ServerWatchInfo): Promise<void> {
     // public/ + public-dev/ 감시
     publicWatcher = await watchPublicFiles(info.pkgDir, true);
 
-    // 의존성 기반 감시 경로 수집
-    const { workspaceDeps, replaceDeps } = collectDeps(info.pkgDir, info.cwd, info.replaceDeps);
-
-    const watchPaths: string[] = [];
-
-    // 서버 패키지 자체 + workspace 의존성 패키지 소스
-    const watchDirs = [
-      info.pkgDir,
-      ...workspaceDeps.map((d) => pathx.posixResolve(info.cwd, "packages", d)),
-    ];
-    for (const dir of watchDirs) {
-      watchPaths.push(pathx.posixResolve(dir, "src", "**", "*"));
-    }
-
-    // replaceDeps 의존성 패키지 dist
-    for (const pkg of replaceDeps) {
-      watchPaths.push(pathx.posixResolve(info.cwd, "node_modules", ...pkg.split("/"), "dist", "**", "*.{js,mjs,cjs}"));
-      watchPaths.push(
-        pathx.posixResolve(info.pkgDir, "node_modules", ...pkg.split("/"), "dist", "**", "*.{js,mjs,cjs}"),
-      );
-    }
-
-    // FsWatcher 시작
-    srcWatcher = await FsWatcher.watch(watchPaths);
-
-    srcWatcher.onChange({ delay: 300 }, async (changes) => {
-      try {
-        const hasFileAddOrRemove = changes.some((c) => c.event === "add" || c.event === "unlink");
-
-        if (hasFileAddOrRemove) {
-          sender.send("buildStart", {});
-
-          // 파일 추가/삭제 시 컨텍스트 재생성
-          const newParsedConfig = parseTsconfig(info.pkgDir);
-          const newEntryPoints = getPackageSourceFiles(info.pkgDir, newParsedConfig);
-
-          // package.json이 변경된 경우에만 외부 모듈 재수집
-          const hasPackageJsonChange = changes.some((c) =>
-            c.path.endsWith("package.json"),
-          );
-          if (hasPackageJsonChange) {
-            cachedExternal = collectAllExternals(info.pkgDir, info.externals);
-          }
-          const newExternal = cachedExternal;
-
-          const oldContext = esbuildContext;
-          esbuildContext = undefined; // 선제 초기화 — 생성 실패 시 disposed 참조 방지 (LOGIC-001)
-          try {
-            if (info.output.js) {
-              esbuildContext = await createEsbuildWatchContext(info, newEntryPoints, newExternal);
-            }
-          } finally {
-            if (oldContext != null) {
-              await oldContext.dispose();
-            }
-          }
+    // 의존성 기반 감시 경로 수집 + FsWatcher 감시 루프 시작
+    const { watchPaths } = buildWatchPaths({
+      pkgDir: info.pkgDir,
+      cwd: info.cwd,
+      srcGlobs: ["*"],
+      replaceDeps: info.replaceDeps,
+    });
 
-          const result = await rebuildAll();
-          sender.send("build", result);
-          return;
-        }
-
-        // 파일 변경만 있는 경우: metafile로 필터링
-        if (esbuildContext == null) {
-          sender.send("buildStart", {});
-          const result = await rebuildAll();
-          sender.send("build", result);
-          return;
-        }
-
-        if (lastMetafile == null) {
-          sender.send("buildStart", {});
-          const result = await rebuildAll();
-          sender.send("build", result);
-          return;
-        }
-
-        // metafile 입력 기반 필터링
-        const metafileAbsPaths = new Set(
-          Object.keys(lastMetafile.inputs).map((key) => pathx.posixResolve(info.cwd, key)),
-        );
-
-        const hasRelevantChange = changes.some((c) => metafileAbsPaths.has(c.path));
-
-        if (hasRelevantChange) {
-          sender.send("buildStart", {});
-          const result = await rebuildAll();
-          sender.send("build", result);
-        } else {
-          logger.debug("변경된 파일이 빌드에 포함되지 않아 리빌드 건너뜀");
-        }
-      } catch (err) {
-        sender.send("error", { message: errNs.message(err) });
-      }
+    srcWatcher = await startServerWatchLoop({
+      info,
+      watchPaths,
+      logger,
+      initialExternals: cachedExternal,
+      onBuildStart: () => sender.send("buildStart", {}),
+      onBuild: (result) => sender.send("build", result),
+      onError: (message) => sender.send("error", { message }),
+      rebuild: () => rebuildAll(),
     });
   } catch (err) {
     sender.send("error", { message: errNs.message(err) });

package/src/workers/server-esbuild-context.ts

@@ -0,0 +1,122 @@
+import esbuild from "esbuild";
+import {
+  createServerEsbuildOptions,
+  writeChangedOutputFiles,
+} from "../esbuild/esbuild-config";
+
+/**
+ * esbuild watch context 생성 옵션
+ */
+export interface EsbuildContextOptions {
+  pkgDir: string;
+  entryPoints: string[];
+  env?: Record<string, string>;
+  external: string[];
+}
+
+/** esbuild watch context (모듈 스코프 상태) */
+let context: esbuild.BuildContext | undefined;
+
+/** 마지막 빌드의 metafile (변경 필터링용) */
+let lastMetafile: esbuild.Metafile | undefined;
+
+/**
+ * esbuild watch context를 생성한다.
+ * dev 모드 전용 (metafile:true, write:false).
+ */
+export async function createContext(options: EsbuildContextOptions): Promise<void> {
+  const baseOptions = createServerEsbuildOptions({
+    pkgDir: options.pkgDir,
+    entryPoints: options.entryPoints,
+    env: options.env,
+    external: options.external,
+    dev: true,
+  });
+
+  context = await esbuild.context({
+    ...baseOptions,
+    metafile: true,
+    write: false,
+  });
+}
+
+/**
+ * esbuild rebuild를 실행하고 metafile을 갱신한다.
+ * context가 없으면 null을 반환한다 (tsc-only 경로).
+ */
+export async function rebuild(): Promise<{
+  success: boolean;
+  errors?: string[];
+  warnings?: string[];
+} | null> {
+  if (context == null) return null;
+
+  const result = await context.rebuild();
+
+  if (result.metafile != null) {
+    lastMetafile = result.metafile;
+  }
+
+  if (result.outputFiles) {
+    await writeChangedOutputFiles(result.outputFiles);
+  }
+
+  const errors = result.errors.map((e) => e.text);
+  const warnings = result.warnings.map((w) => w.text);
+
+  return {
+    success: result.errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+  };
+}
+
+/**
+ * esbuild context를 재생성한다 (LOGIC-001).
+ *
+ * 선제 초기화 + try/finally 패턴으로 리소스 해제를 보장한다:
+ * 1. old context를 로컬 변수에 보관
+ * 2. 모듈 참조를 undefined로 선제 초기화 — 생성 실패 시 disposed 참조 방지
+ * 3. 새 context 생성 시도
+ * 4. finally에서 old context dispose — 생성 성공/실패와 무관하게 실행
+ */
+export async function recreateContext(options: EsbuildContextOptions): Promise<void> {
+  const oldContext = context;
+  context = undefined;
+  lastMetafile = undefined;
+
+  try {
+    await createContext(options);
+  } finally {
+    if (oldContext != null) {
+      await oldContext.dispose();
+    }
+  }
+}
+
+/**
+ * esbuild context를 정리하고 상태를 초기화한다.
+ */
+export async function dispose(): Promise<void> {
+  const contextToDispose = context;
+  context = undefined;
+  lastMetafile = undefined;
+
+  if (contextToDispose != null) {
+    await contextToDispose.dispose();
+  }
+}
+
+/**
+ * 마지막 빌드의 metafile을 반환한다 (변경 필터링에 사용).
+ */
+export function getMetafile(): esbuild.Metafile | undefined {
+  return lastMetafile;
+}
+
+/**
+ * esbuild context 존재 여부를 반환한다.
+ */
+export function hasContext(): boolean {
+  return context != null;
+}

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

@@ -6,7 +6,7 @@ import { consola } from "consola";
 import proxy from "@fastify/http-proxy";
 import net from "net";
 import { pathToFileURL } from "url";
-import { registerCleanupHandlers, setupWorkerConsola } from "../utils/worker-utils";
+import { registerCleanupHandlers, setupWorkerConsola } from "../runtime/worker-utils";
 
 //#region Types
 
@@ -136,6 +136,9 @@ async function start(info: ServerRuntimeStartInfo): Promise<void> {
       }
     }
 
+    // main.js import 전에 sourcemap 지원 활성화 (스택 트레이스에 원본 위치 표시)
+    process.setSourceMapsEnabled(true);
+
     // main.js import (서버 인스턴스를 export해야 함)
     logger.debug("main.js 임포트 중...");
     let stepStart = performance.now();