sonamu 0.10.12 → 0.10.13

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;
 }

package/src/syncer/filesystem-dependencies.ts

@@ -0,0 +1,73 @@
+import {
+  constants,
+  type MakeDirectoryOptions,
+  type PathLike,
+  type RmOptions,
+  type Stats,
+} from "node:fs";
+import { access, mkdir, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
+
+export type SyncerFilesystemDependencies = {
+  access(path: PathLike, mode?: number): Promise<void>;
+  mkdir(path: PathLike, options?: MakeDirectoryOptions): Promise<string | undefined>;
+  readFile(path: PathLike, encoding: BufferEncoding): Promise<string>;
+  rm(path: PathLike, options?: RmOptions): Promise<void>;
+  stat(path: PathLike): Promise<Stats>;
+  unlink(path: PathLike): Promise<void>;
+  writeFile(
+    path: PathLike,
+    data: string | NodeJS.ArrayBufferView,
+    encoding?: BufferEncoding,
+  ): Promise<void>;
+};
+
+const defaults: SyncerFilesystemDependencies = {
+  access: (path, mode) => access(path, mode),
+  mkdir: (path, options) => mkdir(path, options),
+  readFile: (path, encoding) => readFile(path, encoding),
+  rm: (path, options) => rm(path, options),
+  stat: (path) => stat(path),
+  unlink: (path) => unlink(path),
+  writeFile: (path, data, encoding) => writeFile(path, data, encoding),
+};
+
+export const syncerFilesystem: SyncerFilesystemDependencies = { ...defaults };
+
+export async function syncerFileExists(path: PathLike): Promise<boolean> {
+  try {
+    await syncerFilesystem.access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 테스트와 임베딩 환경에서 Syncer의 파일시스템 경계를 교체합니다. */
+export function configureSyncerFilesystem(
+  dependencies: Partial<SyncerFilesystemDependencies>,
+): () => void {
+  const restorers: Array<() => void> = [];
+  const override = <Key extends keyof SyncerFilesystemDependencies>(key: Key): void => {
+    if (!(key in dependencies)) return;
+
+    const previousDependency = syncerFilesystem[key];
+    Object.assign(syncerFilesystem, { [key]: dependencies[key] });
+    restorers.push(() => Object.assign(syncerFilesystem, { [key]: previousDependency }));
+  };
+
+  override("access");
+  override("mkdir");
+  override("readFile");
+  override("rm");
+  override("stat");
+  override("unlink");
+  override("writeFile");
+
+  let configured = true;
+  return () => {
+    if (!configured) return;
+    configured = false;
+
+    for (const restore of restorers) restore();
+  };
+}

package/src/syncer/module-loader.ts

@@ -11,6 +11,7 @@ import { globAsync } from "../utils/async-utils";
 import { importMembers } from "../utils/esm-utils";
 import { runtimePath } from "../utils/path-utils";
 import { type AbsolutePath } from "../utils/path-utils";
+import { isFunctionValue, isObjectValue } from "../utils/runtime-value";
 import { readApisFromFile } from "./api-parser";
 
 export type LoadedApis = ExtendedApi[];
@@ -35,7 +36,10 @@ export async function loadApis(): Promise<LoadedApis> {
     Sonamu.apiRootPath,
     "src/application/**/*.{model,frame}.ts", // !! runtimePath 안 씀 주의 !!
   );
-  const modelPaths = (await globAsync(modelPathsPattern)) as AbsolutePath[];
+  const modelPaths =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (await globAsync(
+      modelPathsPattern,
+    )) as AbsolutePath[];
 
   const apis: LoadedApis = [];
   for (const filePath of modelPaths) {
@@ -125,16 +129,16 @@ export async function loadWorkflows() {
       importedMembers
         .filter(({ value }) => {
           return (
-            typeof value === "object" &&
+            isObjectValue(value) &&
             value !== null &&
             "type" in value &&
             value.type === "workflow" &&
             "fn" in value &&
-            typeof value.fn === "function"
+            isFunctionValue(value.fn)
           );
         })
         .map(({ value }) => {
-          return value as WorkflowMetadata;
+          return /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ value as WorkflowMetadata;
         }),
     );
   }

package/src/syncer/syncer-actions.ts

@@ -1,5 +1,4 @@
 import assert from "assert";
-import { mkdir, readFile, writeFile } from "fs/promises";
 import path, { dirname } from "path";
 
 import chalk from "chalk";
@@ -10,10 +9,12 @@ import { AlreadyProcessedException } from "../exceptions/so-exceptions";
 import { Naite } from "../naite/naite";
 import { isTest } from "../utils/controller";
 import { formatCode } from "../utils/formatter";
-import { copyFileWithReplaceCoreToShared, exists } from "../utils/fs-utils";
 import { type AbsolutePath } from "../utils/path-utils";
+import { isObjectValue } from "../utils/runtime-value";
 import { generateTemplate } from "./code-generator";
+import { copyFileWithReplaceCoreToShared } from "./file-copy";
 import { trackWritten } from "./file-tracking";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
 
 // web/.sonamu.env 에 현재 설정값 저장
 export async function actionSyncConfig() {
@@ -22,8 +23,11 @@ export async function actionSyncConfig() {
 
   Naite.t("actionSyncConfig", { content });
   await Promise.all([
-    ...Sonamu.config.sync.targets.map(async (target) => {
-      await writeFile(path.join(Sonamu.appRootPath, target, ".sonamu.env"), content);
+    ...Sonamu.config.sync.targets.map((target) => {
+      return syncerFilesystem.writeFile(
+        path.join(Sonamu.appRootPath, target, ".sonamu.env"),
+        content,
+      );
     }),
     generateTemplate("generated_sso", {}, { overwrite: true }),
   ]);
@@ -88,6 +92,30 @@ export async function actionGenerateHttps(): Promise<AbsolutePath> {
   return res;
 }
 
+/**
+ * 최종 REST caster를 담는 API 전용 validator registry를 재생성합니다.
+ */
+export async function actionGenerateHttpValidators(): Promise<AbsolutePath> {
+  const registryPath =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ path.join(
+      Sonamu.apiRootPath,
+      "src/application/sonamu.validators.generated.ts",
+    ) as AbsolutePath;
+  const policy = Sonamu.config.validation?.zodCompiler;
+  const isAot = isObjectValue(policy) && policy !== null && policy.api === "aot";
+  if (!isAot) {
+    // opt-out/JIT 전환 뒤 AOT compile import가 애플리케이션에 남지 않도록 산출물도 함께 정리합니다.
+    if (await syncerFileExists(registryPath)) {
+      await syncerFilesystem.unlink(registryPath);
+    }
+    return registryPath;
+  }
+
+  const [generatedPath] = await generateTemplate("http_validators", {}, { overwrite: true });
+  assert(generatedPath);
+  return generatedPath;
+}
+
 /**
  * queries.generated.ts 재생성합니다.
  * @returns 생성된 파일 경로 배열.
@@ -137,8 +165,8 @@ export async function actionSyncFilesToTargets(tsPaths: AbsolutePath[]): Promise
               .replace(`/${apiDir}/`, `/${target}/`)
               .replace("/application/", "/services/");
             const dir = dirname(dst);
-            if (!(await exists(dir))) {
-              await mkdir(dir, { recursive: true });
+            if (!(await syncerFileExists(dir))) {
+              await syncerFilesystem.mkdir(dir, { recursive: true });
             }
             const syncHeader = [
               "/**",
@@ -147,7 +175,9 @@ export async function actionSyncFilesToTargets(tsPaths: AbsolutePath[]): Promise
               " */",
             ].join("\n");
             await copyFileWithReplaceCoreToShared(realSrc, dst, syncHeader);
-            await trackWritten(dst as AbsolutePath);
+            await trackWritten(
+              /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ dst as AbsolutePath,
+            );
             !isTest() &&
               console.log(
                 chalk.bold("Copied: ") + chalk.blue(dst.replace(`${Sonamu.appRootPath}/`, "")),
@@ -174,7 +204,9 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
     import.meta.dirname.replace("/dist/", "/src/"),
     "../dict/utils.ts",
   );
-  const dictUtilsCode = (await exists(dictUtilsPath)) ? await readFile(dictUtilsPath, "utf-8") : "";
+  const dictUtilsCode = (await syncerFileExists(dictUtilsPath))
+    ? await syncerFilesystem.readFile(dictUtilsPath, "utf-8")
+    : "";
 
   // 특정 변수 치환을 위해서 사용합니다.
   const convertMap = {
@@ -192,16 +224,16 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
       import.meta.dirname.replace("/dist/", "/src/"),
       `../shared/${target}.shared.ts.txt`,
     );
-    if (!(await exists(srcPath))) {
+    if (!(await syncerFileExists(srcPath))) {
       continue;
     }
-    if (!(await exists(path.join(Sonamu.appRootPath, target)))) {
+    if (!(await syncerFileExists(path.join(Sonamu.appRootPath, target)))) {
       throw new Error(
         `Tried to copy sonamu.shared.ts to target '${target}' but the target directory does not exist. Please check your project directory structure.`,
       );
     }
 
-    const fullText = await readFile(srcPath, "utf-8");
+    const fullText = await syncerFilesystem.readFile(srcPath, "utf-8");
     const convertedText = Object.entries(convertMap).reduce(
       (acc, [key, value]) => acc.replace(`$[[${key}]]`, value),
       fullText,
@@ -211,8 +243,8 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
     const destPath = path.join(Sonamu.appRootPath, target, "src/services/sonamu.shared.ts");
 
     // 정말 혹시나지만 target 디렉토리는 있어도 src/services 디렉토리는 없을 수 있으므로 미리 생성해줍니다.
-    if (!(await exists(path.dirname(destPath)))) {
-      await mkdir(path.dirname(destPath), { recursive: true });
+    if (!(await syncerFileExists(path.dirname(destPath)))) {
+      await syncerFilesystem.mkdir(path.dirname(destPath), { recursive: true });
       console.warn(`Created directory '${path.dirname(destPath)}' because it did not exist.`);
     }
 
@@ -221,11 +253,11 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
     // 최초 1회만 생성하고 이후에는 덮어쓰지 않습니다.
     // 템플릿 내용($[[dictUtils]] 등)이 변경되었을 때 반영이 필요하면,
     // 해당 파일을 삭제한 뒤 `pnpm sonamu sync`로 재생성하면 됩니다.
-    if (await exists(destPath)) {
+    if (await syncerFileExists(destPath)) {
       continue;
     }
 
-    await writeFile(destPath, await formatCode(convertedText, destPath));
+    await syncerFilesystem.writeFile(destPath, await formatCode(convertedText, destPath));
     !isTest() &&
       console.log(chalk.bold("Copied: ") + chalk.blue(path.relative(Sonamu.appRootPath, destPath)));
   }
@@ -244,7 +276,11 @@ export async function actionSyncSonamuDictionary(): Promise<void> {
   const { targets } = Sonamu.config.sync;
   const i18nConfig = Sonamu.config.i18n;
 
-  const targetList = ["api", ...targets] as ("api" | "web" | "app")[];
+  const targetList =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ [
+      "api",
+      ...targets,
+    ] as ("api" | "web" | "app")[];
 
   const apiI18nDir = path.join(Sonamu.appRootPath, Sonamu.config.api.dir, "src/i18n");
 
@@ -273,7 +309,7 @@ async function syncLocaleFiles(
   const targetI18nDir = path.join(Sonamu.appRootPath, target, "src/i18n");
 
   // 디렉토리가 없으면 생성
-  await mkdir(targetI18nDir, { recursive: true });
+  await syncerFilesystem.mkdir(targetI18nDir, { recursive: true });
 
   for (const locale of locales) {
     const sourceFile = path.join(apiI18nDir, `${locale}.ts`);
@@ -286,7 +322,9 @@ async function syncLocaleFiles(
       " */",
     ].join("\n");
     await copyFileWithReplaceCoreToShared(sourceFile, targetFile, syncHeader);
-    await trackWritten(targetFile as AbsolutePath);
+    await trackWritten(
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ targetFile as AbsolutePath,
+    );
     !isTest() &&
       console.log(chalk.bold("Copied: ") + chalk.cyan(`${target}/src/i18n/${locale}.ts`));
   }