sonamu 0.10.11 → 0.10.13

package/src/syncer/__tests__/http-validator-registry.test.ts

@@ -0,0 +1,137 @@
+import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { type SonamuConfig } from "../../api/config";
+import { Sonamu } from "../../api/sonamu";
+import { type AbsolutePath } from "../../utils/path-utils";
+import { Syncer, type SyncerDependencies } from "../syncer";
+import { actionGenerateHttpValidators } from "../syncer-actions";
+
+function toAbsolutePath(filePath: string): AbsolutePath {
+  if (!path.isAbsolute(filePath)) {
+    throw new Error(`절대 경로가 필요합니다: ${filePath}`);
+  }
+  // SAFETY: path.isAbsolute 검사로 AbsolutePath 계약을 확인했다.
+  return filePath as AbsolutePath;
+}
+
+function createDependencies() {
+  return {
+    actionCopySharedToTargetsIfNotExists: vi
+      .fn<SyncerDependencies["actionCopySharedToTargetsIfNotExists"]>()
+      .mockResolvedValue(undefined),
+    actionGenerateHttpValidators: vi.fn<SyncerDependencies["actionGenerateHttpValidators"]>(),
+    actionGenerateSsrEntryServerIfNotExists: vi
+      .fn<SyncerDependencies["actionGenerateSsrEntryServerIfNotExists"]>()
+      .mockResolvedValue([]),
+    findChangedFilesUsingChecksums: vi.fn<SyncerDependencies["findChangedFilesUsingChecksums"]>(),
+    renewChecksums: vi.fn<SyncerDependencies["renewChecksums"]>().mockResolvedValue(undefined),
+  } satisfies SyncerDependencies;
+}
+
+const testConfig = {
+  api: { dir: "api", route: { prefix: "/api" } },
+  i18n: { defaultLocale: "ko", supportedLocales: ["ko"] },
+  sync: { targets: [] },
+  database: {},
+  server: {
+    apiConfig: {
+      contextProvider: (defaultContext) => defaultContext,
+      guardHandler: () => undefined,
+    },
+  },
+} satisfies SonamuConfig;
+
+describe("HTTP validator registry sync 정리", () => {
+  const tempRoots: string[] = [];
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await Promise.all(
+      tempRoots.splice(0).map((rootPath) => rm(rootPath, { recursive: true, force: true })),
+    );
+  });
+
+  it.each([
+    { label: "opt-out", value: false as const },
+    { label: "JIT", value: { api: "jit" as const } },
+  ])("$label 정책은 남아 있는 generated registry를 제거한다", async ({ value }) => {
+    const apiRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-registry-sync-test-"));
+    tempRoots.push(apiRootPath);
+    const registryPath = path.join(apiRootPath, "src/application/sonamu.validators.generated.ts");
+    await mkdir(path.dirname(registryPath), { recursive: true });
+    await writeFile(registryPath, "export const validators = new Map();\n");
+    Sonamu.apiRootPath = toAbsolutePath(apiRootPath);
+    Sonamu.config = {
+      ...testConfig,
+      api: { ...testConfig.api, dir: "." },
+      validation: { zodCompiler: value },
+    };
+
+    await actionGenerateHttpValidators();
+
+    await expect(access(registryPath)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("registry-only drift를 경고로 넘기지 않고 즉시 재생성한다", async () => {
+    const appRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-registry-drift-test-"));
+    tempRoots.push(appRootPath);
+    const apiRootPath = path.join(appRootPath, "api");
+    const registryPath = toAbsolutePath(
+      path.join(apiRootPath, "src/application/sonamu.validators.generated.ts"),
+    );
+    await mkdir(path.dirname(registryPath), { recursive: true });
+    await writeFile(registryPath, "// drifted registry\n");
+    Sonamu.apiRootPath = toAbsolutePath(apiRootPath);
+    Sonamu.config = {
+      ...testConfig,
+      validation: { zodCompiler: { api: "aot" } },
+    };
+    const dependencies = createDependencies();
+    dependencies.actionGenerateHttpValidators.mockResolvedValue(registryPath);
+    dependencies.findChangedFilesUsingChecksums.mockResolvedValue([registryPath]);
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await new Syncer(dependencies).sync();
+
+    expect(dependencies.actionGenerateHttpValidators).toHaveBeenCalledTimes(1);
+    expect(dependencies.renewChecksums).toHaveBeenCalledTimes(1);
+  });
+
+  it("삭제된 registry가 checksum 변경 목록에서 빠져도 다른 tracked 변경 처리 중 복구한다", async () => {
+    const appRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-missing-registry-test-"));
+    tempRoots.push(appRootPath);
+    const apiRootPath = path.join(appRootPath, "api");
+    const registryPath = toAbsolutePath(
+      path.join(apiRootPath, "src/application/sonamu.validators.generated.ts"),
+    );
+    const unrelatedPath = toAbsolutePath(
+      path.join(apiRootPath, "src/application/queries.generated.ts"),
+    );
+    await mkdir(path.dirname(unrelatedPath), { recursive: true });
+    await writeFile(unrelatedPath, "// unrelated tracked change\n");
+    Sonamu.apiRootPath = toAbsolutePath(apiRootPath);
+    Sonamu.config = {
+      ...testConfig,
+      validation: { zodCompiler: { api: "aot" } },
+    };
+    const order: string[] = [];
+    const dependencies = createDependencies();
+    dependencies.actionGenerateHttpValidators.mockImplementation(async () => {
+      order.push("registry");
+      return registryPath;
+    });
+    dependencies.findChangedFilesUsingChecksums.mockResolvedValue([unrelatedPath]);
+    dependencies.renewChecksums.mockImplementation(async () => {
+      order.push("checksum");
+    });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await new Syncer(dependencies).sync();
+
+    expect(order).toEqual(["registry", "checksum"]);
+  });
+});

package/src/syncer/api-parser.ts

@@ -77,7 +77,7 @@ export async function readApisFromFile(filePath: AbsolutePath): Promise<Extended
         return resolveParamDec(
           {
             name: paramDec.name,
-            type: paramDec.type as ts.TypeNode,
+            type: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ paramDec.type as ts.TypeNode,
             optional: paramDec.questionToken !== undefined || paramDec.initializer !== undefined,
             defaultDef,
           },
@@ -253,7 +253,10 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
     case ts.SyntaxKind.VoidKeyword:
       return "void";
     case ts.SyntaxKind.LiteralType: {
-      const literal = (typeNode as ts.LiteralTypeNode).literal;
+      const literal =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.LiteralTypeNode
+        ).literal;
       if (ts.isStringLiteral(literal)) {
         return {
           t: "string-literal",
@@ -278,35 +281,46 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
       }
     }
     case ts.SyntaxKind.ArrayType: {
-      const arrNode = typeNode as ts.ArrayTypeNode;
+      const arrNode =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ typeNode as ts.ArrayTypeNode;
       return {
         t: "array",
         elementsType: resolveTypeNode(arrNode.elementType),
       };
     }
     case ts.SyntaxKind.TypeLiteral: {
-      const literalNode = typeNode as ts.TypeLiteralNode;
+      const literalNode =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ typeNode as ts.TypeLiteralNode;
       return {
         t: "object",
         props: literalNode.members.map((member) => {
           if (ts.isIndexSignatureDeclaration(member)) {
             assert(member.parameters[0]);
             const res = resolveParamDec({
-              name: member.parameters[0].name as ts.Identifier,
-              type: member.parameters[0].type as ts.TypeNode,
+              name: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ member
+                .parameters[0].name as ts.Identifier,
+              type: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ member
+                .parameters[0].type as ts.TypeNode,
             });
 
             return resolveParamDec({
-              name: {
+              name: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ {
                 escapedText: `[${res.name}${res.optional ? "?" : ""}: ${res.type}]`,
               } as ts.Identifier,
               type: member.type,
             });
           } else {
             return resolveParamDec({
-              name: (member as ts.PropertySignature).name as ts.Identifier,
-              type: (member as ts.PropertySignature).type as ts.TypeNode,
-              optional: (member as ts.PropertySignature).questionToken !== undefined,
+              name: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+                member as ts.PropertySignature
+              ).name as ts.Identifier,
+              type: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+                member as ts.PropertySignature
+              ).type as ts.TypeNode,
+              optional:
+                /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+                  member as ts.PropertySignature
+                ).questionToken !== undefined,
             });
           }
         }),
@@ -315,26 +329,40 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
     case ts.SyntaxKind.TypeReference:
       return {
         t: "ref",
-        id: ((typeNode as ts.TypeReferenceNode).typeName as ts.Identifier).escapedText.toString(),
-        args: (typeNode as ts.TypeReferenceNode).typeArguments?.map((typeArg) =>
-          resolveTypeNode(typeArg),
-        ),
+        id: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          (typeNode as ts.TypeReferenceNode).typeName as ts.Identifier
+        ).escapedText.toString(),
+        args: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.TypeReferenceNode
+        ).typeArguments?.map((typeArg) => resolveTypeNode(typeArg)),
       };
     case ts.SyntaxKind.UnionType:
       return {
         t: "union",
-        types: (typeNode as ts.UnionTypeNode).types.map((type) => resolveTypeNode(type)),
+        types: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.UnionTypeNode
+        ).types.map((type) => resolveTypeNode(type)),
       };
     case ts.SyntaxKind.IntersectionType:
       return {
         t: "intersection",
-        types: (typeNode as ts.IntersectionTypeNode).types.map((type) => resolveTypeNode(type)),
+        types: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.IntersectionTypeNode
+        ).types.map((type) => resolveTypeNode(type)),
       };
     case ts.SyntaxKind.IndexedAccessType:
       return {
         t: "indexed-access",
-        object: resolveTypeNode((typeNode as ts.IndexedAccessTypeNode).objectType),
-        index: resolveTypeNode((typeNode as ts.IndexedAccessTypeNode).indexType),
+        object: resolveTypeNode(
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.IndexedAccessTypeNode
+          ).objectType,
+        ),
+        index: resolveTypeNode(
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.IndexedAccessTypeNode
+          ).indexType,
+        ),
       };
     case ts.SyntaxKind.TupleType:
       if (ts.isTupleTypeNode(typeNode)) {
@@ -347,18 +375,29 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
     case ts.SyntaxKind.ParenthesizedType:
       // 괄호로 묶인 타입 (예: (A & B)[] 에서 (A & B))
       // 내부 타입을 재귀적으로 resolve
-      return resolveTypeNode((typeNode as ts.ParenthesizedTypeNode).type);
+      return resolveTypeNode(
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.ParenthesizedTypeNode
+        ).type,
+      );
 
     case ts.SyntaxKind.FunctionType:
       return {
         t: "function",
-        parameters: (typeNode as ts.FunctionTypeNode).parameters.map((param) => ({
-          name: param.name.getText(),
-          type: param.type ? resolveTypeNode(param.type) : "unknown",
-          optional: param.questionToken !== undefined,
-          defaultDef: undefined,
-        })),
-        returnType: resolveTypeNode((typeNode as ts.FunctionTypeNode).type),
+        parameters:
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.FunctionTypeNode
+          ).parameters.map((param) => ({
+            name: param.name.getText(),
+            type: param.type ? resolveTypeNode(param.type) : "unknown",
+            optional: param.questionToken !== undefined,
+            defaultDef: undefined,
+          })),
+        returnType: resolveTypeNode(
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.FunctionTypeNode
+          ).type,
+        ),
       };
     case undefined:
       throw new Error(`typeNode undefined`);
@@ -377,7 +416,8 @@ function resolveParamDec(
   },
   index: number = 0,
 ): ApiParam {
-  const name = paramDec.name as ts.Identifier;
+  const name =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ paramDec.name as ts.Identifier;
   const type = resolveTypeNode(paramDec.type);
 
   if (name === undefined) {

package/src/syncer/checksum.ts

@@ -1,6 +1,5 @@
 import crypto from "crypto";
 import { createReadStream, type PathLike } from "fs";
-import { readFile, writeFile } from "fs/promises";
 import path from "path";
 
 import equal from "fast-deep-equal";
@@ -8,10 +7,10 @@ import { isEqual } from "radashi";
 
 import { Sonamu } from "../api/sonamu";
 import { globAsync } from "../utils/async-utils";
-import { exists } from "../utils/fs-utils";
 import { type AbsolutePath, type AppRelativePath } from "../utils/path-utils";
 import { differenceWith } from "../utils/utils";
 import { getChecksumPatternGroupInAbsolutePath, GLOB_EXCLUDE } from "./file-patterns";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
 
 type PathAndChecksum = {
   path: AbsolutePath;
@@ -61,7 +60,10 @@ async function getCurrentChecksums(): Promise<PathAndChecksum[]> {
 
   // 동일 파일이 여러 패턴에 매치될 수 있으므로(예: sd.generated.ts는 generated와 sdGenerated에 모두 매치)
   // 중복 제거 후 안정 정렬.
-  const filePaths = Array.from(new Set(allPaths)).toSorted() as AbsolutePath[];
+  const filePaths =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ Array.from(
+      new Set(allPaths),
+    ).toSorted() as AbsolutePath[];
 
   return await Promise.all(
     filePaths.map(async (filePath) => {
@@ -75,17 +77,18 @@ async function getCurrentChecksums(): Promise<PathAndChecksum[]> {
 
 async function getPreviousChecksums(): Promise<PathAndChecksum[]> {
   const checksumFilePath = getChecksumFilePath();
-  if (!(await exists(checksumFilePath))) {
+  if (!(await syncerFileExists(checksumFilePath))) {
     return [];
   }
 
   try {
-    const previousChecksums = JSON.parse(await readFile(checksumFilePath, "utf-8")).map(
-      (r: { path: AppRelativePath; checksum: string }) => ({
+    const previousChecksums =
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ JSON.parse(
+        await syncerFilesystem.readFile(checksumFilePath, "utf-8"),
+      ).map((r: { path: AppRelativePath; checksum: string }) => ({
         path: path.join(Sonamu.appRootPath, r.path), // 체크섬 파일에서 읽을 때: appRoot 상대 경로 → 절대 경로
         checksum: r.checksum,
-      }),
-    ) as PathAndChecksum[];
+      })) as PathAndChecksum[];
     return previousChecksums;
   } catch (e) {
     // 체크섬 파일이 손상된 경우 빈 배열 반환 (전체 재동기화 유도)
@@ -98,7 +101,10 @@ async function getPreviousChecksums(): Promise<PathAndChecksum[]> {
 }
 
 function getChecksumFilePath(): AbsolutePath {
-  return path.join(Sonamu.apiRootPath, "sonamu.lock") as AbsolutePath;
+  return /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ path.join(
+    Sonamu.apiRootPath,
+    "sonamu.lock",
+  ) as AbsolutePath;
 }
 
 async function saveChecksums(checksums: PathAndChecksum[]): Promise<void> {
@@ -109,8 +115,8 @@ async function saveChecksums(checksums: PathAndChecksum[]): Promise<void> {
       path: path.relative(Sonamu.appRootPath, r.path), // 체크섬 파일에 저장할 때: 절대 경로 → appRoot 상대 경로
       checksum: r.checksum,
     }))
-    .sort((a, b) => a.path.localeCompare(b.path));
-  await writeFile(checksumFilePath, JSON.stringify(serialized, null, 2), "utf-8");
+    .toSorted((a, b) => a.path.localeCompare(b.path));
+  await syncerFilesystem.writeFile(checksumFilePath, JSON.stringify(serialized, null, 2), "utf-8");
 }
 
 async function getChecksumOfFile(filePath: PathLike): Promise<string> {

package/src/syncer/code-generator.ts

@@ -1,4 +1,3 @@
-import { mkdir, writeFile } from "fs/promises";
 import path from "path";
 
 import chalk from "chalk";
@@ -21,10 +20,10 @@ import {
 import { everyAsync, filterAsync } from "../utils/async-utils";
 import { isTest } from "../utils/controller";
 import { formatCode } from "../utils/formatter";
-import { exists } from "../utils/fs-utils";
 import { wrapIf } from "../utils/lodash-able";
 import { type AbsolutePath } from "../utils/path-utils";
 import { trackWritten } from "./file-tracking";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
 
 /**
  * 템플릿을 렌더링하고 파일로 생성합니다.
@@ -51,8 +50,8 @@ export async function generateTemplate<T extends TemplateKey>(
   // 템플릿 렌더
   const pathAndCodes = (
     await Promise.all(
-      keys.map(async (key) => {
-        return await renderTemplate(key, templateOptions);
+      keys.map(async (templateKey) => {
+        return await renderTemplate(templateKey, templateOptions);
       }),
     )
   ).flat();
@@ -65,7 +64,10 @@ export async function generateTemplate<T extends TemplateKey>(
         const { targets } = Sonamu.config.sync;
         const filePath = `${Sonamu.appRootPath}/${pathAndCode.path}`;
         const dstFilePaths = targets.map((target) => filePath.replace("/:target/", `/${target}/`));
-        return await everyAsync(dstFilePaths, async (dstPath) => !(await exists(dstPath)));
+        return await everyAsync(
+          dstFilePaths,
+          async (dstPath) => !(await syncerFileExists(dstPath)),
+        );
       });
     }
   })();
@@ -103,8 +105,8 @@ export async function renderTemplate<T extends keyof TemplateOptions>(
   if (rendered.preTemplates) {
     preTemplateResolved = (
       await Promise.all(
-        rendered.preTemplates.map(({ key, options }) => {
-          return renderTemplate(key, options);
+        rendered.preTemplates.map(({ key: preTemplateKey, options: preTemplateOptions }) => {
+          return renderTemplate(preTemplateKey, preTemplateOptions);
         }),
       )
     ).flat();
@@ -122,7 +124,10 @@ async function resolveRenderedTemplate(
   const { target, path: filePath, body, importKeys, customHeaders } = result;
 
   // import 할 대상의 대상 path 추출
-  const builtInSchemaNames = Object.values(BUILT_IN_TYPES).map((info) => info.schemaName as string);
+  const builtInSchemaNames = Object.values(BUILT_IN_TYPES).map(
+    (info) =>
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ info.schemaName as string,
+  );
   const importDefs = importKeys
     // 내장 타입 스키마는 이미 sonamu에서 import되므로 제외
     .filter((importKey) => !builtInSchemaNames.includes(importKey))
@@ -157,7 +162,7 @@ async function resolveRenderedTemplate(
         }
         return r;
       },
-      [] as {
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ [] as {
         keys: string[];
         from: string;
       }[],
@@ -178,12 +183,12 @@ async function resolveRenderedTemplate(
       return [header, body].join("\n\n");
     } else {
       Naite.t("resolveRenderedTemplate:beforeFormat", { key, header, body });
-      const formatted = await formatCode(
+      const formattedCode = await formatCode(
         [header, body].join("\n\n"),
         `${Sonamu.appRootPath}/${filePath}`,
       );
-      Naite.t(`resolveRenderedTemplate:formatted:${key}`, formatted);
-      return formatted;
+      Naite.t(`resolveRenderedTemplate:formatted:${key}`, formattedCode);
+      return formattedCode;
     }
   })();
 
@@ -196,18 +201,21 @@ async function resolveRenderedTemplate(
 async function writeCodeToPathEachTarget(pathAndCode: PathAndCode): Promise<AbsolutePath[]> {
   const { targets } = Sonamu.config.sync;
   const { appRootPath } = Sonamu;
-  const filePath = `${Sonamu.appRootPath}/${pathAndCode.path}` as AbsolutePath;
+  const filePath =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ `${Sonamu.appRootPath}/${pathAndCode.path}` as AbsolutePath;
 
   const dstFilePaths = unique(
-    targets.map((target) => filePath.replace("/:target/", `/${target}/`)) as AbsolutePath[],
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ targets.map(
+      (target) => filePath.replace("/:target/", `/${target}/`),
+    ) as AbsolutePath[],
   );
   return await Promise.all(
     dstFilePaths.map(async (dstFilePath) => {
       const dir = path.dirname(dstFilePath);
-      if (!(await exists(dir))) {
-        await mkdir(dir, { recursive: true });
+      if (!(await syncerFileExists(dir))) {
+        await syncerFilesystem.mkdir(dir, { recursive: true });
       }
-      await writeFile(dstFilePath, pathAndCode.code);
+      await syncerFilesystem.writeFile(dstFilePath, pathAndCode.code);
       // 방금 우리가 쓴 path를 등록 → dev watcher의 후속 change 이벤트가
       // 외부 변경으로 오인되지 않도록 거름 가드 자료 제공.
       await trackWritten(dstFilePath);

package/src/syncer/entity-operations.ts

@@ -1,5 +1,3 @@
-import { rm } from "fs/promises";
-
 import chalk from "chalk";
 
 import { Sonamu } from "../api/sonamu";
@@ -8,8 +6,8 @@ import { EntityManager } from "../entity/entity-manager";
 import { BadRequestException } from "../exceptions/so-exceptions";
 import { type TemplateOptions } from "../types/types";
 import { isTest } from "../utils/controller";
-import { exists } from "../utils/fs-utils";
 import { generateTemplate } from "./code-generator";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
 
 /**
  * 새로운 엔티티를 생성합니다.
@@ -53,9 +51,9 @@ export async function delEntity(entityId: string): Promise<{ delPaths: string[]
   })(); // iife
 
   for (const delPath of delPaths) {
-    if (await exists(delPath)) {
+    if (await syncerFileExists(delPath)) {
       !isTest() && console.log(chalk.red(`DELETE ${delPath}`));
-      await rm(delPath, { recursive: true, force: true });
+      await syncerFilesystem.rm(delPath, { recursive: true, force: true });
     } else {
       !isTest() && console.log(chalk.yellow(`NOT_EXISTS ${delPath}`));
     }

package/src/syncer/file-copy.ts

@@ -0,0 +1,46 @@
+import path, { dirname } from "node:path";
+
+import { formatCode } from "../utils/formatter";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
+
+/**
+ * Syncer 파일시스템 경계를 통해 파일을 복사하고 클라이언트용 import 경로를 변환합니다.
+ */
+export async function copyFileWithReplaceCoreToShared(
+  fromPath: string,
+  toPath: string,
+  syncHeader?: string,
+): Promise<boolean> {
+  if (!(await syncerFileExists(fromPath))) {
+    return false;
+  }
+
+  const oldFileContent = await syncerFilesystem.readFile(fromPath, "utf-8");
+  let newFileContent = replaceCoreImport(oldFileContent, toPath);
+
+  if (syncHeader) {
+    const generatedBlockRegex = /\/\*\*\r?\n \* @generated\r?\n[\s\S]*?\*\/\r?\n(\r?\n)*/;
+    newFileContent = generatedBlockRegex.test(newFileContent)
+      ? newFileContent.replace(generatedBlockRegex, `${syncHeader}\n\n`)
+      : `${syncHeader}\n\n${newFileContent}`;
+  }
+
+  if (toPath.endsWith(".ts") || toPath.endsWith(".tsx")) {
+    newFileContent = await formatCode(newFileContent, toPath);
+  }
+
+  await syncerFilesystem.writeFile(toPath, newFileContent);
+  return true;
+}
+
+function replaceCoreImport(source: string, toPath: string): string {
+  const srcMatch = toPath.match(/^(.+\/src)\//);
+  if (!srcMatch) {
+    return source;
+  }
+
+  const servicesDir = path.join(srcMatch[1], "services");
+  const relativePath = path.relative(dirname(toPath), servicesDir);
+  const sharedPath = relativePath === "" ? "./sonamu.shared" : `${relativePath}/sonamu.shared`;
+  return source.replace(/from "sonamu(\/dict)?"/g, `from "${sharedPath}"`);
+}

package/src/syncer/file-patterns.ts

@@ -56,6 +56,7 @@ export function getChecksumPatternGroup() {
     // 여기에는 Sonamu의 모든 sync 산출물이 있는 것은 아닙니다.
     // sonamu.shared.ts와 entry-server.generated.tsx와 같은
     // sync 초반 1회성 부트스트랩 파일들은 관리 안 하기 때문에 여기에 리스팅도 안 합니다.
+    httpValidatorsGenerated: api("src/application/**/sonamu.validators.generated.ts"),
     generated: api("src/application/**/*.generated.{ts,tsx,sso.ts}"),
     generatedCopied: targets("src/services/**/sonamu.generated.{ts,tsx}"),
     httpGenerated: api("src/application/**/*.generated.http"),
@@ -67,6 +68,11 @@ export function getChecksumPatternGroup() {
   } satisfies Record<string, AppRelativePath>;
 }
 
+// Node 내장 fs.glob의 brace expansion은 단일 멤버 {x}를 풀지 않으므로, 멤버가 1개일 때는 alternation 없이 직접 결합합니다.
+function braceJoin(dirs: readonly string[]) {
+  return dirs.length === 1 ? dirs[0] : `{${dirs.join(",")}}`;
+}
+
 /**
  * 위치 카테고리별 글롭 빌더를 만들어 반환합니다.
  * - api(rest): api 디렉토리에 한정
@@ -77,16 +83,13 @@ function globBuilders() {
   const apiDir = Sonamu.config.api.dir;
   const targetDirs = Sonamu.config.sync.targets;
 
-  // Node 내장 fs.glob의 brace expansion은 단일 멤버 {x}를 풀지 않으므로, 멤버가 1개일 때는 alternation 없이 직접 결합합니다.
-  const braceJoin = (dirs: readonly string[]) =>
-    dirs.length === 1 ? dirs[0] : `{${dirs.join(",")}}`;
-
   return {
-    api: (pathFromApi: string) => `${apiDir}/${pathFromApi}` as AppRelativePath,
+    api: (pathFromApi: string) =>
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ `${apiDir}/${pathFromApi}` as AppRelativePath,
     targets: (pathFromTarget: string) =>
-      `${braceJoin(targetDirs)}/${pathFromTarget}` as AppRelativePath,
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ `${braceJoin(targetDirs)}/${pathFromTarget}` as AppRelativePath,
     anywhere: (pathFromAnywhere: string) =>
-      `${braceJoin([apiDir, ...targetDirs])}/${pathFromAnywhere}` as AppRelativePath,
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ `${braceJoin([apiDir, ...targetDirs])}/${pathFromAnywhere}` as AppRelativePath,
   };
 }
 
@@ -110,7 +113,7 @@ export const GLOB_EXCLUDE = ["**/node_modules/**", "**/dist/**", "**/build/**",
  */
 export function getChecksumPatternGroupInAbsolutePath(): GlobPattern<AbsolutePath> {
   const group = getChecksumPatternGroup();
-  return Object.fromEntries(
+  return /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ Object.fromEntries(
     Object.entries(group).map(([key, value]) => [
       key,
       path.join(Sonamu.appRootPath, value), // appRoot 상대 경로 → 절대 경로

package/src/syncer/file-tracking.ts

@@ -1,6 +1,5 @@
-import { stat } from "fs/promises";
-
 import { type AbsolutePath } from "../utils/path-utils";
+import { syncerFilesystem } from "./filesystem-dependencies";
 
 export const fileWrittenAt = new Map<AbsolutePath, number>();
 
@@ -9,7 +8,7 @@ export const fileWrittenAt = new Map<AbsolutePath, number>();
  * 디스크에서 mtime을 직접 읽어 정확한 값으로 등록합니다.
  */
 export async function trackWritten(filePath: AbsolutePath): Promise<void> {
-  const fileStat = await stat(filePath);
+  const fileStat = await syncerFilesystem.stat(filePath);
   fileWrittenAt.set(filePath, fileStat.mtimeMs);
 }
 
@@ -22,6 +21,6 @@ export async function isLastChangedByMe(filePath: AbsolutePath): Promise<boolean
   if (registered === undefined) {
     return false;
   }
-  const fileStat = await stat(filePath);
+  const fileStat = await syncerFilesystem.stat(filePath);
   return fileStat.mtimeMs <= registered;
 }