@spfn/core 0.3.0-beta.4 → 0.3.0-beta.6

package/dist/env/loader.js

@@ -26,9 +26,10 @@ function parseEnvFile(filePath) {
   return parse(readFileSync(filePath, "utf-8"));
 }
 function loadEnv(options = {}) {
+  const nodeEnvAtEntry = process.env.NODE_ENV;
   const {
     cwd = process.cwd(),
-    nodeEnv = process.env.NODE_ENV || "local",
+    nodeEnv = nodeEnvAtEntry || "local",
     server = true,
     debug = false,
     override = false
@@ -58,8 +59,30 @@ function loadEnv(options = {}) {
     envLogger.debug(`Loaded env files: ${loadedFiles.join(", ")}`);
     envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);
   }
+  warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, options.nodeEnv, nodeEnv);
   return { loadedFiles, loadedKeys };
 }
+function warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, explicitNodeEnv, resolvedNodeEnv) {
+  if (nodeEnvAtEntry || explicitNodeEnv) {
+    return;
+  }
+  const declared = process.env.NODE_ENV;
+  if (!declared) {
+    envLogger.warn(
+      `NODE_ENV is not set anywhere; env files were resolved for "${resolvedNodeEnv}". Set NODE_ENV in the process environment to choose the file set.`
+    );
+    return;
+  }
+  if (declared === resolvedNodeEnv) {
+    return;
+  }
+  if (!existsSync(resolve(cwd, `.env.${declared}`))) {
+    return;
+  }
+  envLogger.warn(
+    `.env.${declared} was NOT loaded: NODE_ENV was not set when the process started, so env files were resolved for "${resolvedNodeEnv}" before a file declared NODE_ENV=${declared}. Set NODE_ENV in the process environment, not in a .env file.`
+  );
+}
 var isEnvLoaded = false;
 function loadEnvOnce(options = {}) {
   if (isEnvLoaded) {

package/dist/env/loader.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/env/loader.ts"],"names":[],"mappings":"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","file":"loader.js","sourcesContent":["/**\n * Environment Variable Loader\n *\n * Next.js 스타일의 환경변수 파일 로딩 (환경별 분리 지원)\n *\n * 로딩 우선순위 (낮음 -> 높음, 나중 파일이 덮어씀):\n * 1. .env                   - 기본값 (committed)\n * 2. .env.{NODE_ENV}        - 환경별 오버라이드 (committed)\n * 3. .env.local             - 로컬 오버라이드 (gitignored, test에서 스킵)\n * 4. .env.{NODE_ENV}.local  - 환경별 시크릿 (gitignored)\n * 5. .env.server            - 서버 전용 (gitignored, Next.js 미로드)\n *\n * @example\n * ```typescript\n * import { loadEnv } from '@spfn/core/env/loader';\n *\n * // 기본 사용 (NODE_ENV 자동 감지)\n * loadEnv();\n *\n * // 특정 환경 지정\n * loadEnv({ nodeEnv: 'production' });\n *\n * // 서버 레이어 제외 (Next.js 클라이언트용)\n * loadEnv({ server: false });\n * ```\n *\n * @module env/loader\n */\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse } from 'dotenv';\nimport { logger } from '@spfn/core/logger';\n\nconst envLogger = logger.child('@spfn/core:env-loader');\n\n/**\n * loadEnv 옵션\n */\nexport interface LoadEnvOptions\n{\n    /**\n     * 프로젝트 루트 경로\n     * @default process.cwd()\n     */\n    cwd?: string;\n\n    /**\n     * NODE_ENV 값 (환경별 .env 파일 결정)\n     * @default process.env.NODE_ENV || 'local'\n     */\n    nodeEnv?: string;\n\n    /**\n     * 서버 전용 파일 포함 여부 (.env.server)\n     * @default true\n     */\n    server?: boolean;\n\n    /**\n     * 디버그 모드 (로드된 파일 로깅)\n     * @default false\n     */\n    debug?: boolean;\n\n    /**\n     * 기존 process.env 값 덮어쓰기 허용\n     * @default false\n     */\n    override?: boolean;\n}\n\n/**\n * 환경변수 로드 결과\n */\nexport interface LoadEnvResult\n{\n    /**\n     * 로드된 파일 목록\n     */\n    loadedFiles: string[];\n\n    /**\n     * 로드된 환경변수 키 목록\n     */\n    loadedKeys: string[];\n}\n\n/**\n * NODE_ENV에 따른 .env 파일 목록 생성 (우선순위 낮음 -> 높음)\n *\n * 더 구체적인 파일이 승리:\n * - environment > base\n * - server > shared\n * - local > committed\n */\nfunction getEnvFiles(nodeEnv: string, server: boolean): string[]\n{\n    const files: string[] = [\n        '.env',\n        `.env.${nodeEnv}`,\n    ];\n\n    // test 환경에서는 .env.local 스킵 (테스트 결정론성 보장)\n    if (nodeEnv !== 'test')\n    {\n        files.push('.env.local');\n    }\n\n    files.push(`.env.${nodeEnv}.local`);\n\n    if (server)\n    {\n        files.push('.env.server');\n    }\n\n    return files;\n}\n\n/**\n * 단일 .env 파일 파싱\n */\nfunction parseEnvFile(filePath: string): Record<string, string> | null\n{\n    if (!existsSync(filePath))\n    {\n        return null;\n    }\n\n    return parse(readFileSync(filePath, 'utf-8'));\n}\n\n/**\n * 프로젝트 루트의 환경변수 파일들을 규칙에 따라 로드\n *\n * 모든 파일을 파싱 후 머지한 뒤 process.env에 한번에 적용.\n * 이미 process.env에 존재하는 키는 덮어쓰지 않음 (플랫폼 주입 보호).\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (로드된 파일, 키 목록)\n */\nexport function loadEnv(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    const {\n        cwd = process.cwd(),\n        nodeEnv = process.env.NODE_ENV || 'local',\n        server = true,\n        debug = false,\n        override = false,\n    } = options;\n\n    const envFiles = getEnvFiles(nodeEnv, server);\n    const loadedFiles: string[] = [];\n\n    // 1) 기존 process.env 키 스냅샷 저장\n    const existingKeys = new Set(Object.keys(process.env));\n\n    // 2) 모든 .env 파일 파싱 후 머지 (나중 파일이 승리)\n    const merged: Record<string, string> = {};\n\n    for (const fileName of envFiles)\n    {\n        const filePath = resolve(cwd, fileName);\n        const parsed = parseEnvFile(filePath);\n\n        if (parsed === null)\n        {\n            continue;\n        }\n\n        loadedFiles.push(fileName);\n        Object.assign(merged, parsed);\n    }\n\n    // 3) 머지된 결과를 process.env에 적용\n    const loadedKeys: string[] = [];\n\n    for (const [key, value] of Object.entries(merged))\n    {\n        // 기존 process.env에 이미 있는 키는 스킵 (override가 false일 때)\n        if (!override && existingKeys.has(key))\n        {\n            continue;\n        }\n\n        process.env[key] = value;\n        loadedKeys.push(key);\n    }\n\n    if (debug && loadedFiles.length > 0)\n    {\n        envLogger.debug(`Loaded env files: ${loadedFiles.join(', ')}`);\n        envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);\n    }\n\n    return { loadedFiles, loadedKeys };\n}\n\n/**\n * 환경변수가 이미 로드되었는지 확인하는 플래그\n */\nlet isEnvLoaded = false;\n\n/**\n * 환경변수를 한 번만 로드 (중복 호출 방지)\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (이미 로드된 경우 빈 결과)\n */\nexport function loadEnvOnce(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    if (isEnvLoaded)\n    {\n        return { loadedFiles: [], loadedKeys: [] };\n    }\n\n    isEnvLoaded = true;\n\n    return loadEnv(options);\n}\n\n/**\n * 환경변수 로드 상태 리셋 (테스트용)\n */\nexport function resetEnvLoadState(): void\n{\n    isEnvLoaded = false;\n}\n"]}
+{"version":3,"sources":["../../src/env/loader.ts"],"names":[],"mappings":";;;;;;AAkCA,IAAM,SAAA,GAAY,MAAA,CAAO,KAAA,CAAM,uBAAuB,CAAA;AA8DtD,SAAS,WAAA,CAAY,SAAiB,MAAA,EACtC;AACI,EAAA,MAAM,KAAA,GAAkB;AAAA,IACpB,MAAA;AAAA,IACA,QAAQ,OAAO,CAAA;AAAA,GACnB;AAGA,EAAA,IAAI,YAAY,MAAA,EAChB;AACI,IAAA,KAAA,CAAM,KAAK,YAAY,CAAA;AAAA,EAC3B;AAEA,EAAA,KAAA,CAAM,IAAA,CAAK,CAAA,KAAA,EAAQ,OAAO,CAAA,MAAA,CAAQ,CAAA;AAElC,EAAA,IAAI,MAAA,EACJ;AACI,IAAA,KAAA,CAAM,KAAK,aAAa,CAAA;AAAA,EAC5B;AAEA,EAAA,OAAO,KAAA;AACX;AAKA,SAAS,aAAa,QAAA,EACtB;AACI,EAAA,IAAI,CAAC,UAAA,CAAW,QAAQ,CAAA,EACxB;AACI,IAAA,OAAO,IAAA;AAAA,EACX;AAEA,EAAA,OAAO,KAAA,CAAM,YAAA,CAAa,QAAA,EAAU,OAAO,CAAC,CAAA;AAChD;AAWO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EACnD;AAGI,EAAA,MAAM,cAAA,GAAiB,QAAQ,GAAA,CAAI,QAAA;AAEnC,EAAA,MAAM;AAAA,IACF,GAAA,GAAM,QAAQ,GAAA,EAAI;AAAA,IAClB,UAAU,cAAA,IAAkB,OAAA;AAAA,IAC5B,MAAA,GAAS,IAAA;AAAA,IACT,KAAA,GAAQ,KAAA;AAAA,IACR,QAAA,GAAW;AAAA,GACf,GAAI,OAAA;AAEJ,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,OAAA,EAAS,MAAM,CAAA;AAC5C,EAAA,MAAM,cAAwB,EAAC;AAG/B,EAAA,MAAM,eAAe,IAAI,GAAA,CAAI,OAAO,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAC,CAAA;AAGrD,EAAA,MAAM,SAAiC,EAAC;AAExC,EAAA,KAAA,MAAW,YAAY,QAAA,EACvB;AACI,IAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,GAAA,EAAK,QAAQ,CAAA;AACtC,IAAA,MAAM,MAAA,GAAS,aAAa,QAAQ,CAAA;AAEpC,IAAA,IAAI,WAAW,IAAA,EACf;AACI,MAAA;AAAA,IACJ;AAEA,IAAA,WAAA,CAAY,KAAK,QAAQ,CAAA;AACzB,IAAA,MAAA,CAAO,MAAA,CAAO,QAAQ,MAAM,CAAA;AAAA,EAChC;AAGA,EAAA,MAAM,aAAuB,EAAC;AAE9B,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAChD;AAEI,IAAA,IAAI,CAAC,QAAA,IAAY,YAAA,CAAa,GAAA,CAAI,GAAG,CAAA,EACrC;AACI,MAAA;AAAA,IACJ;AAEA,IAAA,OAAA,CAAQ,GAAA,CAAI,GAAG,CAAA,GAAI,KAAA;AACnB,IAAA,UAAA,CAAW,KAAK,GAAG,CAAA;AAAA,EACvB;AAEA,EAAA,IAAI,KAAA,IAAS,WAAA,CAAY,MAAA,GAAS,CAAA,EAClC;AACI,IAAA,SAAA,CAAU,MAAM,CAAA,kBAAA,EAAqB,WAAA,CAAY,IAAA,CAAK,IAAI,CAAC,CAAA,CAAE,CAAA;AAC7D,IAAA,SAAA,CAAU,KAAA,CAAM,CAAA,OAAA,EAAU,UAAA,CAAW,MAAM,CAAA,sBAAA,CAAwB,CAAA;AAAA,EACvE;AAEA,EAAA,2BAAA,CAA4B,GAAA,EAAK,cAAA,EAAgB,OAAA,CAAQ,OAAA,EAAS,OAAO,CAAA;AAEzE,EAAA,OAAO,EAAE,aAAa,UAAA,EAAW;AACrC;AAmBA,SAAS,2BAAA,CACL,GAAA,EACA,cAAA,EACA,eAAA,EACA,eAAA,EAEJ;AAEI,EAAA,IAAI,kBAAkB,eAAA,EACtB;AACI,IAAA;AAAA,EACJ;AAEA,EAAA,MAAM,QAAA,GAAW,QAAQ,GAAA,CAAI,QAAA;AAE7B,EAAA,IAAI,CAAC,QAAA,EACL;AACI,IAAA,SAAA,CAAU,IAAA;AAAA,MACN,8DAA8D,eAAe,CAAA,kEAAA;AAAA,KAEjF;AAEA,IAAA;AAAA,EACJ;AAEA,EAAA,IAAI,aAAa,eAAA,EACjB;AACI,IAAA;AAAA,EACJ;AAGA,EAAA,IAAI,CAAC,WAAW,OAAA,CAAQ,GAAA,EAAK,QAAQ,QAAQ,CAAA,CAAE,CAAC,CAAA,EAChD;AACI,IAAA;AAAA,EACJ;AAEA,EAAA,SAAA,CAAU,IAAA;AAAA,IACN,CAAA,KAAA,EAAQ,QAAQ,CAAA,gGAAA,EACsB,eAAe,qCACtC,QAAQ,CAAA,8DAAA;AAAA,GAC3B;AACJ;AAKA,IAAI,WAAA,GAAc,KAAA;AAQX,SAAS,WAAA,CAAY,OAAA,GAA0B,EAAC,EACvD;AACI,EAAA,IAAI,WAAA,EACJ;AACI,IAAA,OAAO,EAAE,WAAA,EAAa,EAAC,EAAG,UAAA,EAAY,EAAC,EAAE;AAAA,EAC7C;AAEA,EAAA,WAAA,GAAc,IAAA;AAEd,EAAA,OAAO,QAAQ,OAAO,CAAA;AAC1B;AAKO,SAAS,iBAAA,GAChB;AACI,EAAA,WAAA,GAAc,KAAA;AAClB","file":"loader.js","sourcesContent":["/**\n * Environment Variable Loader\n *\n * Next.js 스타일의 환경변수 파일 로딩 (환경별 분리 지원)\n *\n * 로딩 우선순위 (낮음 -> 높음, 나중 파일이 덮어씀):\n * 1. .env                   - 기본값 (committed)\n * 2. .env.{NODE_ENV}        - 환경별 오버라이드 (committed)\n * 3. .env.local             - 로컬 오버라이드 (gitignored, test에서 스킵)\n * 4. .env.{NODE_ENV}.local  - 환경별 시크릿 (gitignored)\n * 5. .env.server            - 서버 전용 (gitignored, Next.js 미로드)\n *\n * @example\n * ```typescript\n * import { loadEnv } from '@spfn/core/env/loader';\n *\n * // 기본 사용 (NODE_ENV 자동 감지)\n * loadEnv();\n *\n * // 특정 환경 지정\n * loadEnv({ nodeEnv: 'production' });\n *\n * // 서버 레이어 제외 (Next.js 클라이언트용)\n * loadEnv({ server: false });\n * ```\n *\n * @module env/loader\n */\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse } from 'dotenv';\nimport { logger } from '@spfn/core/logger';\n\nconst envLogger = logger.child('@spfn/core:env-loader');\n\n/**\n * loadEnv 옵션\n */\nexport interface LoadEnvOptions\n{\n    /**\n     * 프로젝트 루트 경로\n     * @default process.cwd()\n     */\n    cwd?: string;\n\n    /**\n     * NODE_ENV 값 (환경별 .env 파일 결정)\n     * @default process.env.NODE_ENV || 'local'\n     */\n    nodeEnv?: string;\n\n    /**\n     * 서버 전용 파일 포함 여부 (.env.server)\n     * @default true\n     */\n    server?: boolean;\n\n    /**\n     * 디버그 모드 (로드된 파일 로깅)\n     * @default false\n     */\n    debug?: boolean;\n\n    /**\n     * 기존 process.env 값 덮어쓰기 허용\n     * @default false\n     */\n    override?: boolean;\n}\n\n/**\n * 환경변수 로드 결과\n */\nexport interface LoadEnvResult\n{\n    /**\n     * 로드된 파일 목록\n     */\n    loadedFiles: string[];\n\n    /**\n     * 로드된 환경변수 키 목록\n     */\n    loadedKeys: string[];\n}\n\n/**\n * NODE_ENV에 따른 .env 파일 목록 생성 (우선순위 낮음 -> 높음)\n *\n * 더 구체적인 파일이 승리:\n * - environment > base\n * - server > shared\n * - local > committed\n */\nfunction getEnvFiles(nodeEnv: string, server: boolean): string[]\n{\n    const files: string[] = [\n        '.env',\n        `.env.${nodeEnv}`,\n    ];\n\n    // test 환경에서는 .env.local 스킵 (테스트 결정론성 보장)\n    if (nodeEnv !== 'test')\n    {\n        files.push('.env.local');\n    }\n\n    files.push(`.env.${nodeEnv}.local`);\n\n    if (server)\n    {\n        files.push('.env.server');\n    }\n\n    return files;\n}\n\n/**\n * 단일 .env 파일 파싱\n */\nfunction parseEnvFile(filePath: string): Record<string, string> | null\n{\n    if (!existsSync(filePath))\n    {\n        return null;\n    }\n\n    return parse(readFileSync(filePath, 'utf-8'));\n}\n\n/**\n * 프로젝트 루트의 환경변수 파일들을 규칙에 따라 로드\n *\n * 모든 파일을 파싱 후 머지한 뒤 process.env에 한번에 적용.\n * 이미 process.env에 존재하는 키는 덮어쓰지 않음 (플랫폼 주입 보호).\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (로드된 파일, 키 목록)\n */\nexport function loadEnv(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    // Captured before any file is read: NODE_ENV decides WHICH files load, so a\n    // value that only arrives from inside a file arrives too late to matter.\n    const nodeEnvAtEntry = process.env.NODE_ENV;\n\n    const {\n        cwd = process.cwd(),\n        nodeEnv = nodeEnvAtEntry || 'local',\n        server = true,\n        debug = false,\n        override = false,\n    } = options;\n\n    const envFiles = getEnvFiles(nodeEnv, server);\n    const loadedFiles: string[] = [];\n\n    // 1) 기존 process.env 키 스냅샷 저장\n    const existingKeys = new Set(Object.keys(process.env));\n\n    // 2) 모든 .env 파일 파싱 후 머지 (나중 파일이 승리)\n    const merged: Record<string, string> = {};\n\n    for (const fileName of envFiles)\n    {\n        const filePath = resolve(cwd, fileName);\n        const parsed = parseEnvFile(filePath);\n\n        if (parsed === null)\n        {\n            continue;\n        }\n\n        loadedFiles.push(fileName);\n        Object.assign(merged, parsed);\n    }\n\n    // 3) 머지된 결과를 process.env에 적용\n    const loadedKeys: string[] = [];\n\n    for (const [key, value] of Object.entries(merged))\n    {\n        // 기존 process.env에 이미 있는 키는 스킵 (override가 false일 때)\n        if (!override && existingKeys.has(key))\n        {\n            continue;\n        }\n\n        process.env[key] = value;\n        loadedKeys.push(key);\n    }\n\n    if (debug && loadedFiles.length > 0)\n    {\n        envLogger.debug(`Loaded env files: ${loadedFiles.join(', ')}`);\n        envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);\n    }\n\n    warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, options.nodeEnv, nodeEnv);\n\n    return { loadedFiles, loadedKeys };\n}\n\n/**\n * Warn when guessing NODE_ENV actually cost the caller something.\n *\n * `getEnvFiles` runs before any file is parsed, so NODE_ENV decides WHICH files\n * load and a value set inside .env.server arrives too late to affect that. The\n * warning therefore reports a missed file, not a missing variable — the previous\n * version announced the variable itself and fired on every boot of a correctly\n * configured app (issue #136).\n *\n * Silent when the guess cost nothing: the guess matched what the files declare,\n * or it did not match but no `.env.<declared>` file exists to have been skipped.\n *\n * @param cwd - project root the files were resolved against\n * @param nodeEnvAtEntry - NODE_ENV as the process was started with\n * @param explicitNodeEnv - nodeEnv passed by the caller, if any\n * @param resolvedNodeEnv - the value the file list was actually built from\n */\nfunction warnIfEnvGuessCostSomething(\n    cwd: string,\n    nodeEnvAtEntry: string | undefined,\n    explicitNodeEnv: string | undefined,\n    resolvedNodeEnv: string,\n): void\n{\n    // Nothing was guessed — the process or the caller named the environment.\n    if (nodeEnvAtEntry || explicitNodeEnv)\n    {\n        return;\n    }\n\n    const declared = process.env.NODE_ENV;\n\n    if (!declared)\n    {\n        envLogger.warn(\n            `NODE_ENV is not set anywhere; env files were resolved for \"${resolvedNodeEnv}\".`\n            + ' Set NODE_ENV in the process environment to choose the file set.',\n        );\n\n        return;\n    }\n\n    if (declared === resolvedNodeEnv)\n    {\n        return;\n    }\n\n    // The guess was wrong, but a file set only goes missing if the file exists.\n    if (!existsSync(resolve(cwd, `.env.${declared}`)))\n    {\n        return;\n    }\n\n    envLogger.warn(\n        `.env.${declared} was NOT loaded: NODE_ENV was not set when the process started,`\n        + ` so env files were resolved for \"${resolvedNodeEnv}\" before a file declared`\n        + ` NODE_ENV=${declared}. Set NODE_ENV in the process environment, not in a .env file.`,\n    );\n}\n\n/**\n * 환경변수가 이미 로드되었는지 확인하는 플래그\n */\nlet isEnvLoaded = false;\n\n/**\n * 환경변수를 한 번만 로드 (중복 호출 방지)\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (이미 로드된 경우 빈 결과)\n */\nexport function loadEnvOnce(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    if (isEnvLoaded)\n    {\n        return { loadedFiles: [], loadedKeys: [] };\n    }\n\n    isEnvLoaded = true;\n\n    return loadEnv(options);\n}\n\n/**\n * 환경변수 로드 상태 리셋 (테스트용)\n */\nexport function resetEnvLoadState(): void\n{\n    isEnvLoaded = false;\n}\n"]}

package/dist/errors/index.js

@@ -1,4 +1,4 @@
-import { format } from 'util';
+import { logger } from '@spfn/core/logger';
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -114,386 +114,6 @@ __export(http_errors_exports, {
   UnsupportedMediaTypeError: () => UnsupportedMediaTypeError,
   ValidationError: () => ValidationError
 });
-
-// src/logger/types.ts
-var LOG_LEVEL_PRIORITY = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  fatal: 4
-};
-
-// src/logger/formatters.ts
-var SENSITIVE_KEYS = [
-  "password",
-  "passwd",
-  "pwd",
-  "secret",
-  "token",
-  "apikey",
-  "api_key",
-  "accesstoken",
-  "access_token",
-  "refreshtoken",
-  "refresh_token",
-  "authorization",
-  "auth",
-  "cookie",
-  "session",
-  "sessionid",
-  "session_id",
-  "privatekey",
-  "private_key",
-  "creditcard",
-  "credit_card",
-  "cardnumber",
-  "card_number",
-  "cvv",
-  "ssn",
-  "pin"
-];
-var MASKED_VALUE = "***MASKED***";
-function isSensitiveKey(key) {
-  const lowerKey = key.toLowerCase();
-  return SENSITIVE_KEYS.some((sensitive) => lowerKey.includes(sensitive));
-}
-function maskSensitiveData(data, seen = /* @__PURE__ */ new WeakSet()) {
-  if (data === null || data === void 0) {
-    return data;
-  }
-  if (typeof data !== "object") {
-    return data;
-  }
-  if (seen.has(data)) {
-    return "[Circular]";
-  }
-  seen.add(data);
-  if (Array.isArray(data)) {
-    return data.map((item) => maskSensitiveData(item, seen));
-  }
-  const masked = {};
-  for (const [key, value] of Object.entries(data)) {
-    if (isSensitiveKey(key)) {
-      masked[key] = MASKED_VALUE;
-    } else if (typeof value === "object" && value !== null) {
-      masked[key] = maskSensitiveData(value, seen);
-    } else {
-      masked[key] = value;
-    }
-  }
-  return masked;
-}
-var COLORS = {
-  reset: "\x1B[0m",
-  bright: "\x1B[1m",
-  dim: "\x1B[2m",
-  // 로그 레벨 컬러
-  debug: "\x1B[36m",
-  // cyan
-  info: "\x1B[32m",
-  // green
-  warn: "\x1B[33m",
-  // yellow
-  error: "\x1B[31m",
-  // red
-  fatal: "\x1B[35m",
-  // magenta
-  // 추가 컬러
-  gray: "\x1B[90m"
-};
-function formatTimestampHuman(date) {
-  const year = date.getFullYear();
-  const month = String(date.getMonth() + 1).padStart(2, "0");
-  const day = String(date.getDate()).padStart(2, "0");
-  const hours = String(date.getHours()).padStart(2, "0");
-  const minutes = String(date.getMinutes()).padStart(2, "0");
-  const seconds = String(date.getSeconds()).padStart(2, "0");
-  const ms = String(date.getMilliseconds()).padStart(3, "0");
-  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
-}
-function formatError(error) {
-  const lines = [];
-  lines.push(`${error.name}: ${error.message}`);
-  if (error.stack) {
-    const stackLines = error.stack.split("\n").slice(1);
-    lines.push(...stackLines);
-  }
-  if (error.cause instanceof Error) {
-    lines.push(`Caused by: ${formatError(error.cause)}`);
-  } else if (error.cause !== void 0) {
-    lines.push(`Caused by: ${String(error.cause)}`);
-  }
-  return lines.join("\n");
-}
-function formatConsole(metadata, colorize = true) {
-  const parts = [];
-  const timestamp = formatTimestampHuman(metadata.timestamp);
-  if (colorize) {
-    parts.push(`${COLORS.gray}[${timestamp}]${COLORS.reset}`);
-  } else {
-    parts.push(`[${timestamp}]`);
-  }
-  const pid = process.pid;
-  if (colorize) {
-    parts.push(`${COLORS.dim}[pid=${pid}]${COLORS.reset}`);
-  } else {
-    parts.push(`[pid=${pid}]`);
-  }
-  if (metadata.module) {
-    if (colorize) {
-      parts.push(`${COLORS.dim}[module=${metadata.module}]${COLORS.reset}`);
-    } else {
-      parts.push(`[module=${metadata.module}]`);
-    }
-  }
-  if (metadata.context && Object.keys(metadata.context).length > 0) {
-    Object.entries(metadata.context).forEach(([key, value]) => {
-      let valueStr;
-      if (typeof value === "string") {
-        valueStr = value;
-      } else if (typeof value === "object" && value !== null) {
-        try {
-          valueStr = JSON.stringify(value);
-        } catch (error) {
-          valueStr = "[circular]";
-        }
-      } else {
-        valueStr = String(value);
-      }
-      if (colorize) {
-        parts.push(`${COLORS.dim}[${key}=${valueStr}]${COLORS.reset}`);
-      } else {
-        parts.push(`[${key}=${valueStr}]`);
-      }
-    });
-  }
-  const levelStr = metadata.level.toUpperCase();
-  if (colorize) {
-    const color = COLORS[metadata.level];
-    parts.push(`${color}(${levelStr})${COLORS.reset}:`);
-  } else {
-    parts.push(`(${levelStr}):`);
-  }
-  if (colorize) {
-    parts.push(`${COLORS.bright}${metadata.message}${COLORS.reset}`);
-  } else {
-    parts.push(metadata.message);
-  }
-  let output = parts.join(" ");
-  if (metadata.error) {
-    output += "\n" + formatError(metadata.error);
-  }
-  return output;
-}
-
-// src/logger/logger.ts
-var FORMAT_PATTERN = /%[sdifjoOc%]/;
-var Logger = class _Logger {
-  config;
-  module;
-  constructor(config) {
-    this.config = config;
-    this.module = config.module;
-  }
-  /**
-   * Convert unknown error to Error object
-   */
-  toError(error) {
-    if (error instanceof Error) return error;
-    if (typeof error === "string") return new Error(error);
-    if (typeof error === "object" && error !== null) {
-      return new Error(JSON.stringify(error));
-    }
-    return new Error(String(error));
-  }
-  /**
-   * Check if value is a context object (not an error)
-   */
-  isContext(value) {
-    if (typeof value !== "object" || value === null) return false;
-    if (value instanceof Error) return false;
-    const hasStack = "stack" in value && typeof value.stack === "string";
-    if (hasStack) {
-      return false;
-    }
-    return true;
-  }
-  /**
-   * Get current log level
-   */
-  get level() {
-    return this.config.level;
-  }
-  /**
-   * Create child logger (per module)
-   */
-  child(module) {
-    return new _Logger({
-      ...this.config,
-      module
-    });
-  }
-  /**
-   * Common log method with error/context detection
-   */
-  logWithLevel(level, message, errorOrContext, context) {
-    if (errorOrContext !== void 0 && FORMAT_PATTERN.test(message)) {
-      this.log(level, format(message, errorOrContext), void 0, context);
-      return;
-    }
-    if (errorOrContext instanceof Error) {
-      this.log(level, message, errorOrContext, context);
-    } else if (errorOrContext !== void 0 && typeof errorOrContext === "object" && !this.isContext(errorOrContext)) {
-      this.log(level, message, this.toError(errorOrContext), context);
-    } else if (typeof errorOrContext === "string" || typeof errorOrContext === "number" || typeof errorOrContext === "boolean") {
-      this.log(level, message, this.toError(errorOrContext), context);
-    } else {
-      this.log(level, message, void 0, errorOrContext);
-    }
-  }
-  debug(message, errorOrContext, context) {
-    this.logWithLevel("debug", message, errorOrContext, context);
-  }
-  info(message, errorOrContext, context) {
-    this.logWithLevel("info", message, errorOrContext, context);
-  }
-  warn(message, errorOrContext, context) {
-    this.logWithLevel("warn", message, errorOrContext, context);
-  }
-  error(message, errorOrContext, context) {
-    this.logWithLevel("error", message, errorOrContext, context);
-  }
-  fatal(message, errorOrContext, context) {
-    this.logWithLevel("fatal", message, errorOrContext, context);
-  }
-  /**
-   * Log processing (internal)
-   */
-  log(level, message, error, context) {
-    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.config.level]) {
-      return;
-    }
-    const metadata = {
-      timestamp: /* @__PURE__ */ new Date(),
-      level,
-      message,
-      module: this.module,
-      error,
-      // Mask sensitive information in context to prevent credential leaks
-      context: context ? maskSensitiveData(context) : void 0
-    };
-    this.processTransports(metadata);
-  }
-  /**
-   * Process Transports
-   */
-  processTransports(metadata) {
-    const promises = this.config.transports.filter((transport) => transport.enabled).map((transport) => this.safeTransportLog(transport, metadata));
-    Promise.all(promises).catch((error) => {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      process.stderr.write(`[Logger] Transport error: ${errorMessage}
-`);
-    });
-  }
-  /**
-   * Transport log (error-safe)
-   */
-  async safeTransportLog(transport, metadata) {
-    try {
-      await transport.log(metadata);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      process.stderr.write(`[Logger] Transport "${transport.name}" failed: ${errorMessage}
-`);
-    }
-  }
-  /**
-   * Close all Transports
-   */
-  async close() {
-    const closePromises = this.config.transports.filter((transport) => transport.close).map((transport) => transport.close());
-    await Promise.all(closePromises);
-  }
-};
-
-// src/logger/transports/console.ts
-var ConsoleTransport = class {
-  name = "console";
-  level;
-  enabled;
-  colorize;
-  constructor(config) {
-    this.level = config.level;
-    this.enabled = config.enabled;
-    this.colorize = config.colorize ?? true;
-  }
-  async log(metadata) {
-    if (!this.enabled) {
-      return;
-    }
-    if (LOG_LEVEL_PRIORITY[metadata.level] < LOG_LEVEL_PRIORITY[this.level]) {
-      return;
-    }
-    const message = formatConsole(metadata, this.colorize);
-    if (metadata.level === "warn" || metadata.level === "error" || metadata.level === "fatal") {
-      console.error(message);
-    } else {
-      console.log(message);
-    }
-  }
-};
-
-// src/logger/config.ts
-function getConsoleConfig() {
-  const isProduction = process.env.NODE_ENV === "production";
-  return {
-    level: "debug",
-    enabled: true,
-    colorize: !isProduction
-    // Dev: colored output, Production: plain text
-  };
-}
-function validateEnvironment() {
-  const nodeEnv = process.env.NODE_ENV;
-  if (!nodeEnv) {
-    process.stderr.write(
-      "[Logger] Warning: NODE_ENV is not set. Defaulting to test environment.\n"
-    );
-  }
-}
-function validateConfig() {
-  validateEnvironment();
-}
-
-// src/logger/factory.ts
-function initializeTransports() {
-  const transports = [];
-  const consoleConfig = getConsoleConfig();
-  transports.push(new ConsoleTransport(consoleConfig));
-  return transports;
-}
-function getLogLevel() {
-  const envLevel = process.env.SPFN_LOG_LEVEL || process.env.NEXT_PUBLIC_SPFN_LOG_LEVEL || "info";
-  if (envLevel in LOG_LEVEL_PRIORITY) {
-    return envLevel;
-  }
-  process.stderr.write(
-    `[Logger] Invalid log level "${envLevel}", defaulting to "info"
-`
-  );
-  return "info";
-}
-function initializeLogger() {
-  validateConfig();
-  return new Logger({
-    level: getLogLevel(),
-    transports: initializeTransports()
-  });
-}
-var logger = initializeLogger();
-
-// src/errors/serializable-error.ts
 var RESERVED_RESPONSE_KEYS = /* @__PURE__ */ new Set(["__type", "message", "error"]);
 var AUTHORING_ENVIRONMENTS = /* @__PURE__ */ new Set(["local", "development", "test"]);
 function refuseReservedKey(className, key) {