@spfn/core 0.3.0-beta.3 → 0.3.0-beta.30

package/dist/env/index.d.ts

@@ -1,3 +1,4 @@
+export { E as EnvLayer, a as EnvRegistry, b as EnvSchemaCollection, c as EnvValidationResult, d as EnvVarSchema, I as InferEnvType, e as createEnvRegistry, f as defineEnvSchema, g as envBoolean, h as envEnum, i as envJson, j as envNumber, k as envSecret, l as envString, m as envUrl, n as isClientAccessible, o as isNextjsAccessible, p as isServerOnly, q as isSpfnServerOnly, v as validateAllEnv } from '../registry-C2KQCh0m.js';
 export { L as LogLevel } from '../types-BGl4QL1w.js';
 
 /**
@@ -5,6 +6,10 @@ export { L as LogLevel } from '../types-BGl4QL1w.js';
  *
  * Parser functions that transform and validate environment variable strings.
  * All parsers follow the pattern: (value: string) => T or throw Error
+ *
+ * An error message never contains the input. Messages are logged — by the
+ * registry and by the server's boot check — and the input may be a secret or a
+ * URL carrying credentials. Describe the expected shape instead.
  */
 /**
  * Parser function that transforms and validates a string value
@@ -430,447 +435,6 @@ declare function withFallback<T>(parser: Parser<T>, fallback: T): Parser<T>;
  */
 declare function optional<T>(parser: Parser<T>): Parser<T | undefined>;
 
-/**
- * Environment Variable Schema Definition System
- *
- * 환경변수에 메타데이터를 정의하여 중앙 관리, 문서화, 검증을 지원합니다.
- *
- * @example
- * ```typescript
- * const schema = defineEnvSchema({
- *   DATABASE_URL: envUrl({
- *     description: 'Database connection',
- *     required: true,
- *     validator: parsePostgresUrl,
- *     sensitive: true,
- *   })
- * });
- * ```
- *
- * @module env/schema
- */
-/**
- * 환경변수 스키마 정의
- */
-interface EnvVarSchema<T = string> {
-    /** 환경변수 키 */
-    key: string;
-    /** 설명 (목적, 사용처) */
-    description: string;
-    /** 타입 */
-    type: 'string' | 'number' | 'boolean' | 'url' | 'enum' | 'json';
-    /** 필수 여부 */
-    required?: boolean;
-    /** 기본값 */
-    default?: T;
-    /** 검증/변환 함수 */
-    validator?: (value: string) => T;
-    /** Fallback 환경변수 키들 (backward compatibility) */
-    fallbackKeys?: string[];
-    /** 최소 길이 (문자열 타입) */
-    minLength?: number;
-    /** 민감정보 여부 (로깅 시 마스킹) */
-    sensitive?: boolean;
-    /**
-     * 자동 생성 방식 — 값이 미지정이면 프로비저닝(secrets 관리 CLI)이 이 방식으로 생성한다.
-     * 외부에서 받아야 하는 시크릿(API 키 등)은 generate를 비워 사용자 입력으로 둔다.
-     */
-    generate?: 'hex32' | 'hex64' | 'uuid' | 'base64url32';
-    /** 예시 값들 (타입과 일치해야 함) */
-    examples?: T[];
-    /**
-     * Next.js 프로세스에서 사용 여부
-     *
-     * - true: .env.local에 존재해야 함 (Next.js 서버 컴포넌트에서 접근 가능)
-     * - false: .env.server에만 존재해야 함 (SPFN 서버에서만 접근)
-     *
-     * @default NEXT_PUBLIC_* 이면 true, 아니면 false
-     */
-    nextjs?: boolean;
-}
-/**
- * 스키마 컬렉션 타입
- */
-type EnvSchemaCollection = Record<string, EnvVarSchema<any>>;
-/**
- * Helper type: Check if field has default value
- */
-type HasDefault<T> = T extends {
-    default: any;
-} ? true : false;
-/**
- * Helper type: Check if field is explicitly required
- */
-type IsRequired<T> = T extends {
-    required: true;
-} ? true : false;
-/**
- * Helper type: Check if field should be required (has default OR required: true)
- */
-type ShouldBeRequired<T> = HasDefault<T> extends true ? true : IsRequired<T>;
-/**
- * 스키마로부터 타입 추출
- *
- * required: true 또는 default가 있는 필드 → 필수
- * required: false 또는 미지정 → optional (| undefined)
- */
-type InferEnvType<T extends EnvSchemaCollection> = {
-    [K in keyof T as ShouldBeRequired<T[K]> extends true ? K : never]: T[K] extends EnvVarSchema<infer U> ? U : string;
-} & {
-    [K in keyof T as ShouldBeRequired<T[K]> extends true ? never : K]?: T[K] extends EnvVarSchema<infer U> ? U | undefined : string | undefined;
-};
-/**
- * 스키마 정의 헬퍼 (타입 추론 지원)
- *
- * Automatically fills in the `key` property from object keys.
- *
- * @example
- * ```typescript
- * const schema = defineEnvSchema({
- *   DATABASE_URL: envString({ description: 'Database URL', required: true })
- * });
- * // Automatically adds key: 'DATABASE_URL'
- * ```
- */
-declare function defineEnvSchema<T extends Record<string, any>>(schema: T): {
-    [K in keyof T]: T[K] & {
-        key: K;
-    };
-};
-/**
- * 문자열 스키마 헬퍼
- *
- * @example
- * ```typescript
- * const schema = {
- *   API_KEY: {
- *     ...envString({
- *       description: 'API authentication key',
- *       required: true,
- *       sensitive: true,
- *     }),
- *     key: 'API_KEY',
- *   }
- * };
- * ```
- */
-declare function envString<T extends Omit<EnvVarSchema, 'key' | 'type'>>(options: T): T & {
-    type: 'string';
-    validator: (value: string) => string;
-};
-/**
- * 시크릿 스키마 헬퍼 — sensitive:true 자동.
- *
- * generate 지정 시 프로비저닝(secrets CLI)이 값을 자동 생성, 미지정이면 외부 입력(사용자가 붙여넣음).
- * 이로써 env.config.ts가 "설정(envString) vs 외부 시크릿(envSecret) vs 자동 시크릿(envSecret+generate)"을
- * 선언적으로 가른다 — CLI·프레임워크·프로비저닝이 한 원천을 읽는다.
- *
- * @example
- * ```typescript
- * SPFN_AUTH_SESSION_SECRET: envSecret({ description: '세션 서명 키', generate: 'base64url32' }),
- * OPENAI_API_KEY: envSecret({ description: 'OpenAI API 키' }),  // generate 없음 → 외부 입력
- * ```
- */
-declare function envSecret<T extends Omit<EnvVarSchema, 'key' | 'type' | 'sensitive'>>(options: T): T & {
-    type: 'string';
-    sensitive: true;
-    validator: (value: string) => string;
-};
-/**
- * 숫자 스키마 헬퍼
- *
- * @example
- * ```typescript
- * const schema = {
- *   PORT: {
- *     ...envNumber({
- *       description: 'Server port',
- *       default: 3000,
- *       validator: createNumberParser({ min: 1, max: 65535 }),
- *     }),
- *     key: 'PORT',
- *   }
- * };
- * ```
- */
-declare function envNumber<T extends Omit<EnvVarSchema<number>, 'key' | 'type'>>(options: T): T & {
-    type: 'number';
-    validator: (value: string) => number;
-};
-/**
- * Boolean 스키마 헬퍼
- *
- * @example
- * ```typescript
- * const schema = {
- *   DEBUG: {
- *     ...envBoolean({
- *       description: 'Enable debug mode',
- *       default: false,
- *     }),
- *     key: 'DEBUG',
- *   }
- * };
- * ```
- */
-declare function envBoolean<T extends Omit<EnvVarSchema<boolean>, 'key' | 'type'>>(options: T): T & {
-    type: 'boolean';
-    validator: (value: string) => boolean;
-};
-/**
- * URL 스키마 헬퍼
- *
- * @example
- * ```typescript
- * const schema = {
- *   DATABASE_URL: {
- *     ...envUrl({
- *       description: 'Database connection URL',
- *       required: true,
- *       validator: parsePostgresUrl,
- *     }),
- *     key: 'DATABASE_URL',
- *   }
- * };
- * ```
- */
-declare function envUrl<T extends Omit<EnvVarSchema, 'key' | 'type'>>(options: T): T & {
-    type: 'url';
-};
-/**
- * Enum 스키마 헬퍼
- *
- * @example
- * ```typescript
- * const schema = {
- *   LOG_LEVEL: {
- *     ...envEnum(['debug', 'info', 'warn', 'error'] as const, {
- *       description: 'Logging level',
- *       default: 'info',
- *     }),
- *     key: 'LOG_LEVEL',
- *   }
- * };
- * ```
- */
-declare function envEnum<T extends string, O extends Omit<EnvVarSchema<T>, 'key' | 'type' | 'validator'>>(allowed: readonly T[], options: O): O & {
-    type: 'enum';
-    validator: (val: string) => T;
-};
-/**
- * JSON 스키마 헬퍼
- *
- * @example
- * ```typescript
- * const schema = {
- *   CONFIG_JSON: {
- *     ...envJson<{ host: string; port: number }>({
- *       description: 'JSON configuration object',
- *       required: true,
- *     }),
- *     key: 'CONFIG_JSON',
- *   }
- * };
- * ```
- */
-declare function envJson<T = any, O extends Omit<EnvVarSchema<T>, 'key' | 'type' | 'validator'> = Omit<EnvVarSchema<T>, 'key' | 'type' | 'validator'>>(options: O): O & {
-    type: 'json';
-    validator: (val: string) => T;
-};
-/**
- * 환경변수가 클라이언트에서 접근 가능한지 확인
- * (NEXT_PUBLIC_ 접두사로 판단)
- *
- * @param key - 환경변수 키
- * @returns 클라이언트에서 접근 가능하면 true
- *
- * @example
- * ```typescript
- * isClientAccessible('NEXT_PUBLIC_API_URL');  // true
- * isClientAccessible('DATABASE_URL');         // false
- * ```
- */
-declare function isClientAccessible(key: string): boolean;
-/**
- * 환경변수가 서버 전용인지 확인
- * (NEXT_PUBLIC_ 접두사가 없으면 서버 전용)
- *
- * @param key - 환경변수 키
- * @returns 서버 전용이면 true
- *
- * @example
- * ```typescript
- * isServerOnly('DATABASE_URL');              // true
- * isServerOnly('NEXT_PUBLIC_API_URL');       // false
- * ```
- */
-declare function isServerOnly(key: string): boolean;
-/**
- * 스키마의 nextjs 옵션 값 결정
- *
- * 명시적으로 지정되지 않은 경우:
- * - NEXT_PUBLIC_* → true
- * - 그 외 → false
- *
- * @param schema - 환경변수 스키마
- * @returns Next.js 프로세스에서 사용 가능 여부
- */
-declare function isNextjsAccessible(schema: EnvVarSchema): boolean;
-/**
- * 스키마가 SPFN 서버 전용인지 확인
- *
- * @param schema - 환경변수 스키마
- * @returns SPFN 서버에서만 사용되면 true
- */
-declare function isSpfnServerOnly(schema: EnvVarSchema): boolean;
-
-/**
- * Environment Variable Registry
- *
- * 환경변수 스키마를 등록하고 타입 안전하게 접근할 수 있는 레지스트리
- *
- * @example
- * ```typescript
- * const schema = defineEnvSchema({
- *   DATABASE_URL: envString({ description: 'Database URL', required: true })
- * });
- *
- * const registry = createEnvRegistry(schema);
- * const env = registry.validate(); // 검증 + env 반환
- * console.log(env.DATABASE_URL);
- * ```
- *
- * @module env/registry
- */
-
-/**
- * 환경변수 레지스트리
- *
- * 스키마 기반 환경변수 관리 및 검증
- */
-declare class EnvRegistry<T extends EnvSchemaCollection = EnvSchemaCollection> {
-    private schemas;
-    private hasValidated;
-    constructor(schemas?: T);
-    /**
-     * 스키마 등록
-     */
-    register(schema: EnvVarSchema): void;
-    /**
-     * 여러 스키마 등록
-     */
-    registerMultiple(schemas: EnvSchemaCollection): void;
-    /**
-     * 검증 상태 리셋 (테스트용)
-     */
-    reset(): void;
-    /**
-     * 환경변수 원시값 가져오기 (fallback 지원)
-     */
-    private getRawValue;
-    /**
-     * 값에 validator 적용
-     */
-    private applyValidator;
-    /**
-     * 스키마 검증 수행 (값 읽기 없이)
-     *
-     * @internal
-     */
-    private validateSchemas;
-    /**
-     * SKIP_ENV_VALIDATION 환경변수 확인
-     */
-    private shouldSkipValidation;
-    /**
-     * 실제 접근 시점에 환경변수 값 가져오기 및 검증
-     *
-     * @internal
-     */
-    private getAndValidate;
-    /**
-     * 모든 환경변수를 명시적으로 검증 (SKIP_ENV_VALIDATION 무시)
-     *
-     * CLI에서 사용하기 위한 메서드로, 모든 required 환경변수를 강제 검증합니다.
-     *
-     * @returns 검증 결과 (errors, warnings)
-     */
-    validateAll(): {
-        errors: Array<{
-            key: string;
-            message: string;
-        }>;
-        warnings: Array<{
-            key: string;
-            message: string;
-        }>;
-    };
-    /**
-     * 환경변수 검증 및 타입 안전한 env 객체 반환
-     *
-     * Proxy 기반으로 구현되어 실제 환경변수 접근 시점에 값을 읽고 검증합니다.
-     * 이를 통해 dotenv 로딩 타이밍과 무관하게 최신 환경변수 값을 가져올 수 있습니다.
-     *
-     * @returns 검증된 환경변수 객체 (Proxy)
-     * @throws {Error} 필수 변수 누락 또는 검증 실패 시
-     *
-     * @example
-     * ```typescript
-     * const registry = createEnvRegistry(schema);
-     * const env = registry.validate(); // 스키마만 검증
-     * // ... dotenv 로딩 ...
-     * console.log(env.DATABASE_URL); // 이 시점에 실제 값 읽기
-     * ```
-     */
-    validate(): InferEnvType<T>;
-}
-/**
- * 환경변수 검증 결과
- */
-interface EnvValidationResult {
-    valid: boolean;
-    errors: Array<{
-        key: string;
-        message: string;
-    }>;
-    warnings: Array<{
-        key: string;
-        message: string;
-    }>;
-}
-/**
- * 레지스트리 생성 헬퍼
- *
- * @example
- * ```typescript
- * const schema = defineEnvSchema({
- *   DATABASE_URL: envString({ description: 'Database URL', required: true })
- * });
- *
- * const registry = createEnvRegistry(schema);
- * const env = registry.validate();
- * ```
- */
-declare function createEnvRegistry<T extends EnvSchemaCollection>(schemas: T): EnvRegistry<T>;
-/**
- * 모든 환경변수를 명시적으로 검증 (SKIP_ENV_VALIDATION 무시)
- *
- * CLI `spfn env validate` 명령어에서 사용
- *
- * @param registries - 검증할 레지스트리 배열
- * @returns 검증 결과
- *
- * @example
- * ```typescript
- * const result = validateAllEnv([coreRegistry, authRegistry]);
- * if (!result.valid) {
- *   console.error('Missing env vars:', result.errors);
- *   process.exit(1);
- * }
- * ```
- */
-declare function validateAllEnv(registries: EnvRegistry<any>[]): EnvValidationResult;
-
 /**
  * Environment Types
  */
@@ -879,4 +443,4 @@ declare function validateAllEnv(registries: EnvRegistry<any>[]): EnvValidationRe
  */
 type NodeEnv = 'local' | 'development' | 'staging' | 'production' | 'test';
 
-export { EnvRegistry, type EnvSchemaCollection, type EnvValidationResult, type EnvVarSchema, type InferEnvType, type NodeEnv, type Parser, chain, createArrayParser, createEnumParser, createEnvRegistry, createJsonParser, createNumberParser, createPasswordParser, createSecureSecretParser, createStringParser, createUrlParser, defineEnvSchema, envBoolean, envEnum, envJson, envNumber, envSecret, envString, envUrl, isClientAccessible, isNextjsAccessible, isServerOnly, isSpfnServerOnly, optional, parseArray, parseBoolean, parseDecimal, parseEnum, parseInteger, parseJson, parseNumber, parsePostgresUrl, parseRedisUrl, parseString, parseUrl, validateAllEnv, withFallback };
+export { type NodeEnv, type Parser, chain, createArrayParser, createEnumParser, createJsonParser, createNumberParser, createPasswordParser, createSecureSecretParser, createStringParser, createUrlParser, optional, parseArray, parseBoolean, parseDecimal, parseEnum, parseInteger, parseJson, parseNumber, parsePostgresUrl, parseRedisUrl, parseString, parseUrl, withFallback };

package/dist/env/index.js

@@ -35,9 +35,7 @@ function parseBoolean(value) {
   if (["false", "0", "no"].includes(normalized)) {
     return false;
   }
-  throw new Error(
-    `Must be a boolean value (true/false, 1/0, yes/no), got: ${value}`
-  );
+  throw new Error("Must be a boolean value (true/false, 1/0, yes/no)");
 }
 function parseNumber(value, options = {}) {
   const { min, max, integer = false } = options;
@@ -46,16 +44,16 @@ function parseNumber(value, options = {}) {
   }
   const num = Number(value);
   if (isNaN(num)) {
-    throw new Error(`Must be a valid number, got: ${value}`);
+    throw new Error("Must be a valid number");
   }
   if (integer && !Number.isInteger(num)) {
-    throw new Error(`Must be an integer, got: ${value}`);
+    throw new Error("Must be an integer");
   }
   if (min !== void 0 && num < min) {
-    throw new Error(`Must be at least ${min}, got: ${num}`);
+    throw new Error(`Must be at least ${min}`);
   }
   if (max !== void 0 && num > max) {
-    throw new Error(`Must be at most ${max}, got: ${num}`);
+    throw new Error(`Must be at most ${max}`);
   }
   return num;
 }
@@ -75,7 +73,7 @@ function parseUrl(value, options = {}) {
     url = new URL(value);
   } catch (error) {
     if (error instanceof TypeError) {
-      throw new Error(`Invalid URL: ${value}`);
+      throw new Error("Invalid URL");
     }
     throw error;
   }
@@ -131,14 +129,14 @@ function parseEnum(value, allowed, caseInsensitive = false) {
     const index = normalizedAllowed.indexOf(normalizedValue);
     if (index === -1) {
       throw new Error(
-        `Must be one of [${allowed.join(", ")}], got: ${value}`
+        `Must be one of [${allowed.join(", ")}]`
       );
     }
     return allowed[index];
   }
   if (!allowed.includes(value)) {
     throw new Error(
-      `Must be one of [${allowed.join(", ")}], got: ${value}`
+      `Must be one of [${allowed.join(", ")}]`
     );
   }
   return value;
@@ -149,10 +147,8 @@ function createEnumParser(allowed, caseInsensitive = false) {
 function parseJson(value) {
   try {
     return JSON.parse(value);
-  } catch (error) {
-    throw new Error(
-      `Invalid JSON: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+  } catch {
+    throw new Error("Invalid JSON");
   }
 }
 function createJsonParser() {
@@ -336,7 +332,7 @@ function envEnum(allowed, options) {
     type: "enum",
     validator: (val) => {
       if (!allowed.includes(val)) {
-        throw new Error(`Must be one of: ${allowed.join(", ")}, got: ${val}`);
+        throw new Error(`Must be one of: ${allowed.join(", ")}`);
       }
       return val;
     }
@@ -521,9 +517,10 @@ var EnvRegistry = class {
         try {
           schema.validator(value);
         } catch (error) {
+          const detail = schema.sensitive ? "(value hidden \u2014 sensitive key)" : error instanceof Error ? error.message : String(error);
           errors.push({
             key,
-            message: `${key} validation failed: ${error instanceof Error ? error.message : String(error)}`
+            message: `${key} validation failed: ${detail}`
           });
         }
       }