sonamu 0.10.13 → 0.11.0

package/src/bin/build-config.ts

@@ -1,11 +1,23 @@
-import { readFile, writeFile } from "node:fs/promises";
+import assert from "node:assert";
+import { readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import chalk from "chalk";
 import { type UserConfig } from "tsdown";
 
 import { type NormalizedZodCompilerPolicy } from "../api/config";
+import {
+  execWithLinePrefix,
+  printBuildSummary,
+  printTaskFailed,
+  printTaskHeader,
+  printTaskStart,
+  printTaskSuccess,
+} from "../utils/console-util";
 import { exists } from "../utils/fs-utils";
+import { findApiRootPath, findAppRootPath } from "../utils/utils";
+import { loadBuildCompilerPolicy } from "./compiler-policy";
 
 export type BuildArtifact<BuildCommandArgs = {}> = {
   name: string;
@@ -18,6 +30,21 @@ export type BuildArtifact<BuildCommandArgs = {}> = {
 
 export type ApiTsdownBuildConfig = Pick<UserConfig, "entry" | "plugins">;
 
+export function quoteShellArgument(value: string): string {
+  // 작은따옴표 자체만 셸 경계를 닫지 못하도록 분리해 리터럴 인수를 보존합니다.
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+export function createWebTypecheckCommand(): string {
+  const isSourceModule = path.extname(import.meta.filename) === ".ts";
+  const scriptPath = path.join(
+    import.meta.dirname,
+    `typecheck-web.${isSourceModule ? "ts" : "js"}`,
+  );
+  const runner = isSourceModule ? "pnpm exec tsx" : quoteShellArgument(process.execPath);
+  return `${runner} ${quoteShellArgument(scriptPath)}`;
+}
+
 type ZodCompilerPluginFactory = (typeof import("zod-compiler/rolldown"))["default"];
 
 export interface ApiZodCompilerBuildDependencies {
@@ -184,8 +211,11 @@ export const API_ARTIFACTS: BuildArtifact<{ configFilePath: string }>[] = [
     description: "API 프로젝트 빌드 산출물",
     projectPath: "api",
     preBuildCommand: () => "rm -rf dist",
-    buildCommand: ({ configFilePath }) =>
-      `tsc --noEmit && pnpm exec tsdown --config ${JSON.stringify(configFilePath)}`,
+    buildCommand: ({ configFilePath }) => {
+      const configExtension = path.extname(configFilePath);
+      const configLoader = [".ts", ".tsx"].includes(configExtension) ? " --config-loader tsx" : "";
+      return `tsc --noEmit && pnpm exec tsdown --config ${JSON.stringify(configFilePath)}${configLoader}`;
+    },
   },
 ];
 
@@ -200,7 +230,7 @@ export const WEB_ARTIFACTS: BuildArtifact[] = [
     projectPath: "web",
     preBuildCommand: () => "rm -rf dist/client",
     buildCommand: () =>
-      "tsc -b --noEmit && vite build --config vite.config.ts --outDir dist/client",
+      `${createWebTypecheckCommand()} && vite build --config vite.config.ts --outDir dist/client`,
   },
   {
     name: "Web Server",
@@ -208,8 +238,124 @@ export const WEB_ARTIFACTS: BuildArtifact[] = [
     projectPath: "web",
     preBuildCommand: () => "rm -rf dist/server",
     buildCommand: () =>
-      "tsc -b --noEmit && vite build --config vite.config.ts --ssr src/entry-server.generated.tsx --outDir dist/server",
+      `${createWebTypecheckCommand()} && vite build --config vite.config.ts --ssr src/entry-server.generated.tsx --outDir dist/server`,
     postBuildCommand: () =>
       "rm -rf ../api/web-dist && mkdir -p ../api/web-dist && cp -r dist/* ../api/web-dist",
   },
 ];
+
+export async function resolveApiBuildConfigPath(
+  apiRootPath: string,
+  dependencies: {
+    exists: (candidatePath: string) => Promise<boolean>;
+    moduleDir: string;
+  } = {
+    exists,
+    moduleDir: import.meta.dirname,
+  },
+): Promise<string> {
+  const localConfigPath = path.join(apiRootPath, "tsdown.config.ts");
+  if (await dependencies.exists(localConfigPath)) {
+    console.log(chalk.dim("Using tsdown.config.ts from project root..."));
+    return localConfigPath;
+  }
+
+  console.log(chalk.dim("Using default tsdown API config from sonamu package..."));
+  const compiledConfigPath = path.join(dependencies.moduleDir, "..", "tsdown.api.config.js");
+  if (await dependencies.exists(compiledConfigPath)) {
+    return compiledConfigPath;
+  }
+  return path.join(dependencies.moduleDir, "..", "..", "tsdown.api.config.ts");
+}
+
+async function runBuildSteps<T>(
+  artifact: BuildArtifact<T>,
+  options: { cwd: string; buildCommandArgs: T },
+) {
+  const steps = [
+    { name: "pre-build", cmd: artifact.preBuildCommand?.() },
+    { name: "build", cmd: artifact.buildCommand(options.buildCommandArgs) },
+    { name: "post-build", cmd: artifact.postBuildCommand?.() },
+  ].filter((step) => step.cmd !== undefined);
+
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const isLast = index === steps.length - 1;
+    try {
+      assert(step.cmd);
+      printTaskStart(step.name, step.cmd, isLast);
+      await execWithLinePrefix(step.cmd, { cwd: options.cwd });
+      printTaskSuccess(step.name, isLast);
+    } catch (error) {
+      printTaskFailed(step.name, isLast);
+      throw new Error(`${step.name} failed`, { cause: error });
+    }
+  }
+}
+
+export async function buildApiCommand(): Promise<void> {
+  const apiRootPath = findApiRootPath();
+  const baseConfigPath = await resolveApiBuildConfigPath(apiRootPath);
+  const policy = await loadBuildCompilerPolicy(apiRootPath);
+  const registryPath = path.join(apiRootPath, HTTP_VALIDATOR_REGISTRY_SOURCE_PATH);
+  const configFilePath = await createApiZodCompilerBuildWrapper({
+    apiRootPath,
+    baseConfigPath,
+    policy,
+    registryPath,
+  });
+  const temporaryConfigPath = configFilePath === baseConfigPath ? undefined : configFilePath;
+  const startedAt = Date.now();
+
+  try {
+    for (const artifact of API_ARTIFACTS) {
+      printTaskHeader(artifact.name, artifact.description, apiRootPath);
+      await runBuildSteps(artifact, {
+        cwd: apiRootPath,
+        buildCommandArgs: { configFilePath },
+      });
+    }
+    if (policy.api === "aot") {
+      const outputPath = path.join(apiRootPath, HTTP_VALIDATOR_REGISTRY_BUILD_PATH);
+      if (!(await exists(outputPath))) {
+        throw new Error(`Built HTTP validator registry not found: ${outputPath}`);
+      }
+      assertApiZodCompilerBuildOutput([
+        { code: await readFile(outputPath, "utf8"), path: outputPath },
+      ]);
+    }
+    printBuildSummary("API", true, Date.now() - startedAt);
+  } catch (error) {
+    printBuildSummary("API", false, Date.now() - startedAt);
+    throw error;
+  } finally {
+    if (temporaryConfigPath !== undefined) await rm(temporaryConfigPath, { force: true });
+  }
+}
+
+export async function buildWebCommand({
+  skipIfMissing = false,
+}: { skipIfMissing?: boolean } = {}): Promise<void> {
+  const appRootPath = findAppRootPath();
+  const webPath = path.join(appRootPath, "web");
+  if (!(await exists(webPath))) {
+    if (skipIfMissing) {
+      console.log(chalk.gray("Web 디렉토리가 없으므로 Web 빌드를 건너뜁니다."));
+      return;
+    }
+    throw new Error(`web 디렉토리를 찾을 수 없습니다: ${webPath}`);
+  }
+
+  const startedAt = Date.now();
+  try {
+    for (const artifact of WEB_ARTIFACTS) {
+      const cwd = path.join(appRootPath, artifact.projectPath);
+      printTaskHeader(artifact.name, artifact.description, cwd);
+      await runBuildSteps(artifact, { cwd, buildCommandArgs: {} });
+    }
+    printBuildSummary("Web", true, Date.now() - startedAt);
+  } catch (error) {
+    printBuildSummary("Web", false, Date.now() - startedAt);
+    throw error;
+  }
+}

package/src/bin/fixture.ts

@@ -1,4 +1,8 @@
+import { spawn, type SpawnOptions } from "node:child_process";
+import { open } from "node:fs/promises";
+
 import chalk from "chalk";
+import knex, { type Knex } from "knex";
 import prompts from "prompts";
 import { z } from "zod";
 
@@ -10,18 +14,22 @@ import { getSonamuEnvironment } from "../env";
 import { DataExplorer } from "../testing/data-explorer";
 import { type DataExplorerStrategy } from "../testing/data-explorer";
 import { FixtureGenerator } from "../testing/fixture-generator";
+import { FixtureManager } from "../testing/fixture-manager";
+import { exists } from "../utils/fs-utils";
 
-interface FixtureCommandOptions {
+export interface FixtureCommandOptions {
   _?: string[];
   all?: boolean;
   include?: string;
   exclude?: string;
-  count?: string;
+  count?: string | number;
   "save-to"?: string;
   strategy?: DataExplorerStrategy;
-  limit?: string;
+  limit?: string | number;
   "use-llm"?: boolean;
   "no-cache"?: boolean;
+  nonInteractive?: boolean;
+  userMode?: "login" | "dummy";
 }
 
 interface SignupBody {
@@ -34,6 +42,160 @@ interface SignupBody {
 
 const SignupErrorResponse = z.object({ code: z.string().optional() }).passthrough();
 
+function runProcess(
+  executable: string,
+  args: string[],
+  stdio: SpawnOptions["stdio"] = ["ignore", "inherit", "inherit"],
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { stdio });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(`${executable} 명령이 ${code ?? signal ?? "unknown"} 상태로 실패했습니다.`),
+        );
+    });
+  });
+}
+
+async function writeMysqlDump(args: string[], outputPath: string) {
+  const output = await open(outputPath, "w");
+  try {
+    await runProcess("mysqldump", args, ["ignore", output.fd, "inherit"]);
+  } finally {
+    await output.close();
+  }
+}
+
+async function runMysqlWithInput(args: string[], inputPath: string) {
+  const input = await open(inputPath, "r");
+  try {
+    await runProcess("mysql", args, [input.fd, "inherit", "inherit"]);
+  } finally {
+    await input.close();
+  }
+}
+
+function mysqlConnectionArgs(connection: Knex.ConnectionConfig) {
+  return [
+    `-h${String(connection.host)}`,
+    `-u${String(connection.user)}`,
+    `-p${String(connection.password)}`,
+  ];
+}
+
+export async function fixtureInitCommand(): Promise<void> {
+  const srcConfig = Sonamu.dbConfig[getSonamuEnvironment()];
+  const fixtureConnection =
+    /* SAFETY: Sonamu DB 구성은 초기화 시 Knex 연결 구성으로 검증됩니다. */ Sonamu.dbConfig.fixture
+      .connection as Knex.ConnectionConfig;
+  const testConnection =
+    /* SAFETY: Sonamu DB 구성은 초기화 시 Knex 연결 구성으로 검증됩니다. */ Sonamu.dbConfig.test
+      .connection as Knex.ConnectionConfig;
+  const targets: Array<{ label: string; config: Knex.Config; toSkip?: boolean }> = [
+    { label: "(REMOTE) Fixture DB", config: Sonamu.dbConfig.fixture },
+    {
+      label: "(LOCAL) Testing DB",
+      config: Sonamu.dbConfig.test,
+      // 같은 DB를 가리키면 원격 fixture를 다시 덮어쓰지 않습니다.
+      toSkip:
+        fixtureConnection.host === testConnection.host &&
+        fixtureConnection.database === testConnection.database,
+    },
+  ];
+
+  const dumpFilename = `/tmp/sonamu-fixture-init-${Date.now()}.sql`;
+  const migrationsDump = `/tmp/sonamu-fixture-init-migrations-${Date.now()}.sql`;
+  const srcConnection =
+    /* SAFETY: Sonamu DB 구성은 초기화 시 Knex 연결 구성으로 검증됩니다. */ srcConfig.connection as Knex.ConnectionConfig;
+  await writeMysqlDump(
+    [
+      ...mysqlConnectionArgs(srcConnection),
+      "--single-transaction",
+      "-d",
+      "--no-create-db",
+      "--triggers",
+      String(srcConnection.database),
+    ],
+    dumpFilename,
+  );
+
+  const sourceDb = knex(srcConfig);
+  try {
+    const [[migrations]] = await sourceDb.raw(
+      "SELECT COUNT(*) as count FROM information_schema.tables WHERE table_schema = ? AND table_name = 'knex_migrations'",
+      [srcConnection.database],
+    );
+    if (migrations.count > 0) {
+      await writeMysqlDump(
+        [
+          ...mysqlConnectionArgs(srcConnection),
+          "--single-transaction",
+          "--no-create-db",
+          "--triggers",
+          String(srcConnection.database),
+          "knex_migrations",
+          "knex_migrations_lock",
+        ],
+        migrationsDump,
+      );
+    }
+
+    for (const { label, config, toSkip } of targets) {
+      const connection =
+        /* SAFETY: targets는 검증된 Sonamu DB 구성에서만 조합됩니다. */ config.connection as Knex.ConnectionConfig;
+      if (toSkip === true) {
+        console.log(chalk.red(`${label}: Skipped!`));
+        continue;
+      }
+
+      const databaseConnection =
+        /* SAFETY: targets는 검증된 Sonamu DB 구성에서만 조합됩니다. */ (config.connection ??
+          {}) as Knex.ConnectionConfig;
+      const db = knex({
+        ...config,
+        connection: { ...databaseConnection, database: undefined },
+      });
+      try {
+        const [[row]] = await db.raw(`SHOW DATABASES LIKE "${connection.database}"`);
+        if (row) {
+          console.log(chalk.yellow(`${label}: Database "${connection.database}" Already exists`));
+          continue;
+        }
+
+        const connectionArgs = mysqlConnectionArgs(connection);
+        const database = String(connection.database);
+        const escapedDatabase = database.replaceAll("`", "``");
+        await runProcess("mysql", [
+          ...connectionArgs,
+          "-e",
+          `DROP DATABASE IF EXISTS \`${escapedDatabase}\``,
+        ]);
+        await runProcess("mysql", [
+          ...connectionArgs,
+          "-e",
+          `CREATE DATABASE \`${escapedDatabase}\``,
+        ]);
+        await runMysqlWithInput([...connectionArgs, database], dumpFilename);
+        if (await exists(migrationsDump)) {
+          await runMysqlWithInput([...connectionArgs, database], migrationsDump);
+        }
+      } finally {
+        await db.destroy();
+      }
+    }
+  } finally {
+    await sourceDb.destroy();
+  }
+}
+
+export async function fixtureCleanupCommand(): Promise<void> {
+  await FixtureManager.destroy();
+  await Sonamu.destroy();
+}
+
 /**
  * username을 일반적인 규칙(영문자 시작, 영문자/숫자만, 1-20자)에 맞도록 정규화합니다.
  */
@@ -70,6 +232,11 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
       }
     } else if (options.include) {
       entityNames = options.include.split(",").map((s: string) => s.trim());
+    } else if (options.nonInteractive === true) {
+      throw Object.assign(new Error("Fixture gen selector is required."), {
+        code: "MISSING_ARGUMENT",
+        exitCode: 2,
+      });
     } else {
       const result = await prompts({
         type: "multiselect",
@@ -87,8 +254,8 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
       entityNames = result.entities;
     }
 
-    let count = options.count ? Number.parseInt(options.count, 10) : 5;
-    if (!options.count) {
+    let count = options.count ? Number.parseInt(String(options.count), 10) : 5;
+    if (!options.count && options.nonInteractive !== true) {
       const result = await prompts({
         type: "number",
         name: "count",
@@ -109,25 +276,30 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
     const hasUser = entityNames.includes("User");
 
     if (hasUser) {
-      const userModeResult = await prompts({
-        type: "select",
-        name: "userMode",
-        message: "User 엔티티가 포함되어 있습니다. 생성 방식을 선택하세요:",
-        choices: [
-          { title: "1. 로그인 가능한 사용자 fixture 생성", value: "login" },
-          { title: "2. 확인용 데이터(로그인 불가) 생성", value: "dummy" },
-        ],
-      });
+      let userMode = options.userMode;
+      if (userMode === undefined && options.nonInteractive === true) userMode = "dummy";
+      if (userMode === undefined) {
+        const userModeResult = await prompts({
+          type: "select",
+          name: "userMode",
+          message: "User 엔티티가 포함되어 있습니다. 생성 방식을 선택하세요:",
+          choices: [
+            { title: "1. 로그인 가능한 사용자 fixture 생성", value: "login" },
+            { title: "2. 확인용 데이터(로그인 불가) 생성", value: "dummy" },
+          ],
+        });
+        userMode = userModeResult.userMode;
+      }
 
-      if (!userModeResult.userMode) {
+      if (!userMode) {
         console.log(chalk.yellow("취소되었습니다."));
         return;
       }
 
-      if (userModeResult.userMode === "login") {
+      if (userMode === "login") {
         // LLM 사용 여부
         let useLLM = options["use-llm"] ?? false;
-        if (!options["use-llm"]) {
+        if (options["use-llm"] === undefined && options.nonInteractive !== true) {
           const llmResult = await prompts({
             type: "confirm",
             name: "useLLM",
@@ -232,7 +404,7 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
     }
 
     let saveTarget = options["save-to"] || "db";
-    if (!options["save-to"]) {
+    if (!options["save-to"] && options.nonInteractive !== true) {
       const result = await prompts({
         type: "select",
         name: "saveTarget",
@@ -266,7 +438,7 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
 
     // LLM 사용 여부 결정
     let useLLM = options["use-llm"] ?? false;
-    if (!options["use-llm"]) {
+    if (options["use-llm"] === undefined && options.nonInteractive !== true) {
       const llmResult = await prompts({
         type: "confirm",
         name: "useLLM",
@@ -387,6 +559,11 @@ export async function fixtureFetchCommand(options: FixtureCommandOptions) {
       }
     } else if (options.include) {
       entityNames = options.include.split(",").map((s: string) => s.trim());
+    } else if (options.nonInteractive === true) {
+      throw Object.assign(new Error("Fixture fetch selector is required."), {
+        code: "MISSING_ARGUMENT",
+        exitCode: 2,
+      });
     } else {
       const result = await prompts({
         type: "multiselect",
@@ -405,7 +582,7 @@ export async function fixtureFetchCommand(options: FixtureCommandOptions) {
     }
 
     const strategy: DataExplorerStrategy = options.strategy ?? "recent";
-    const limit = options.limit ? Number.parseInt(options.limit, 10) : 10;
+    const limit = options.limit ? Number.parseInt(String(options.limit), 10) : 10;
 
     // fixture fetch: 현재 환경 데이터를 fixture DB로 import합니다
     const sourceDb = DB.getDB("r");
@@ -449,6 +626,12 @@ export async function fixtureExploreCommand(options: FixtureCommandOptions) {
 
     let entityName = options.include;
 
+    if (!entityName && options.nonInteractive === true) {
+      throw Object.assign(new Error("Fixture explore selector is required."), {
+        code: "MISSING_ARGUMENT",
+        exitCode: 2,
+      });
+    }
     if (!entityName) {
       const result = await prompts({
         type: "select",
@@ -470,7 +653,7 @@ export async function fixtureExploreCommand(options: FixtureCommandOptions) {
     }
 
     const strategy: DataExplorerStrategy = options.strategy ?? "sample";
-    const limit = options.limit ? Number.parseInt(options.limit, 10) : 10;
+    const limit = options.limit ? Number.parseInt(String(options.limit), 10) : 10;
 
     const db = DB.getDB("r");
     const explorer = new DataExplorer(db, EntityManager);

package/src/bin/test-command.ts

@@ -40,6 +40,13 @@ export interface TestCommandDependencies {
   loadConfig: (apiRootPath: string) => Promise<TestCommandConfig>;
 }
 
+export interface LegacyTestCommandInput {
+  files?: readonly string[];
+  pattern?: string;
+  traces?: boolean;
+  status?: boolean;
+}
+
 const testCommandDependencies: TestCommandDependencies = {
   fetch: globalThis.fetch,
   findApiRootPath,
@@ -74,10 +81,6 @@ export async function testCommand(
   dependencies: TestCommandDependencies = testCommandDependencies,
 ): Promise<void> {
   const args = process.argv.slice(3);
-
-  const config = await loadDevServerConfig(dependencies);
-
-  // process.argv 파싱: sonamu test [file...] --pattern "이름" --traces --status
   const files: string[] = [];
   let pattern: string | undefined;
   let showTraces = false;
@@ -96,6 +99,26 @@ export async function testCommand(
     }
   }
 
+  return runTestCommand({ files, pattern, traces: showTraces, status: showStatus }, dependencies);
+}
+
+export async function testCommandWithInput(
+  input: LegacyTestCommandInput,
+  dependencies: TestCommandDependencies = testCommandDependencies,
+): Promise<void> {
+  return runTestCommand(input, dependencies);
+}
+
+async function runTestCommand(
+  input: LegacyTestCommandInput,
+  dependencies: TestCommandDependencies,
+): Promise<void> {
+  const config = await loadDevServerConfig(dependencies);
+  const files = [...(input.files ?? [])];
+  const pattern = input.pattern;
+  const showTraces = input.traces === true;
+  const showStatus = input.status === true;
+
   if (showStatus) {
     return testStatusCommand(config, dependencies.fetch);
   }

package/src/bin/typecheck-web.ts

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import ts from "@typescript/typescript6";
+import { z } from "zod";
+
+const execFileAsync = promisify(execFile);
+const requireFromHere = createRequire(import.meta.url);
+const configPath = path.resolve("tsconfig.json");
+const parsedConfig = ts.parseConfigFileTextToJson(configPath, await readFile(configPath, "utf8"));
+if (parsedConfig.error) {
+  throw new Error(ts.flattenDiagnosticMessageText(parsedConfig.error.messageText, "\n"));
+}
+const configResult = z
+  .object({ references: z.array(z.object({ path: z.string() })).optional() })
+  .safeParse(parsedConfig.config);
+if (!configResult.success) {
+  throw new Error("tsconfig.json의 project references를 읽을 수 없습니다.", {
+    cause: configResult.error,
+  });
+}
+const config = configResult.data;
+const references = config.references ?? [];
+
+if (references.length === 0) {
+  throw new Error("tsconfig.json에 typecheck할 project reference가 없습니다.");
+}
+
+const tscPath = path.join(
+  path.dirname(requireFromHere.resolve("typescript/package.json")),
+  "bin/tsc",
+);
+for (const reference of references) {
+  // Web 앱은 선언을 배포하지 않으므로 참조별 타입 검사에서 선언 직렬화만 비활성화합니다.
+  await execFileAsync(
+    process.execPath,
+    [
+      tscPath,
+      "--noEmit",
+      "--composite",
+      "false",
+      "--declaration",
+      "false",
+      "--declarationMap",
+      "false",
+      "--emitDeclarationOnly",
+      "false",
+      "-p",
+      path.resolve(reference.path),
+    ],
+    { cwd: process.cwd() },
+  );
+}

package/src/dict/sonamu-dictionary.ts

@@ -3,7 +3,7 @@ import fs from "fs";
 import path from "path";
 
 import { Workbook } from "@sheetkit/node";
-import ts from "typescript";
+import ts from "@typescript/typescript6";
 
 import { Sonamu } from "../api/sonamu";
 import { EntityManager } from "../entity/entity-manager";

package/src/entity/__tests__/entity-manager-autoload.contract.test.ts

@@ -0,0 +1,55 @@
+/// <reference types="node" />
+
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+interface EntityManagerModule {
+  readonly EntityManager: {
+    isAutoloaded: boolean;
+    autoload(doSilent?: boolean, apiRootPath?: string): Promise<void>;
+  };
+}
+
+interface SonamuModule {
+  readonly Sonamu: {
+    readonly apiRootPath: string;
+  };
+}
+
+const temporaryRoots: string[] = [];
+
+async function importProduction<T>(relativePath: string): Promise<T> {
+  const loaded: unknown = await import(
+    /* @vite-ignore */ new URL(relativePath, import.meta.url).href
+  );
+  // SAFETY: 테스트는 명시한 singleton 공개 API만 호출합니다.
+  return loaded as T;
+}
+
+afterEach(async () => {
+  await Promise.all(temporaryRoots.splice(0).map((root) => rm(root, { recursive: true })));
+});
+
+describe("EntityManager 명시적 API 루트", () => {
+  it("Sonamu singleton이 초기화되지 않아도 전달한 apiRootPath로 autoload한다", async () => {
+    const [{ EntityManager }, { Sonamu }] = await Promise.all([
+      importProduction<EntityManagerModule>("../entity-manager.ts"),
+      importProduction<SonamuModule>("../../api/sonamu.ts"),
+    ]);
+    const apiRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-entity-autoload-"));
+    temporaryRoots.push(apiRootPath);
+    const previousAutoloaded = EntityManager.isAutoloaded;
+    EntityManager.isAutoloaded = false;
+
+    expect(() => Sonamu.apiRootPath).toThrow(/init/i);
+    try {
+      await expect(EntityManager.autoload(true, apiRootPath)).resolves.toBeUndefined();
+      expect(EntityManager.isAutoloaded).toBe(true);
+    } finally {
+      EntityManager.isAutoloaded = previousAutoloaded;
+    }
+  });
+});