@spfn/core 0.3.0-beta.15 → 0.3.0-beta.16

package/dist/registry-DZHXQ134.d.ts

@@ -0,0 +1,472 @@
+/**
+ * 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;
+    /**
+     * Which layer of a deployment supplies the value.
+     *
+     * - `'environment'`: one value shared by every instance of an environment
+     *   (a third-party API key) — kept in `secrets/<env>.enc.json`.
+     * - `'instance'`: a value that differs per instance — kept in
+     *   `secrets/<env>.<instance>.enc.json` or computed by the deploy script
+     *   and passed to `spfn secret export --with <file>`.
+     *
+     * `spfn secret export` fails when a value arrives from the wrong layer.
+     *
+     * @default 'environment'
+     */
+    layer?: EnvLayer;
+    /**
+     * Files that read this variable under a computed key, as paths relative to
+     * the project root — e.g. `['src/server/config/providers.ts']`.
+     *
+     * `spfn env audit` counts a name as read when it appears as a property
+     * access or a string literal; a name only ever reached through
+     * `env[name]` needs this instead. The name passes when every listed file
+     * exists and is scanned. The runtime ignores `readBy`.
+     */
+    readBy?: string[];
+}
+/**
+ * The layer of a deployment an env value comes from — see {@link EnvVarSchema.layer}.
+ */
+type EnvLayer = 'environment' | 'instance';
+/**
+ * 스키마 컬렉션 타입
+ */
+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. Every other
+ * field passes through as written — an entry without `layer` is an
+ * `'environment'` value.
+ *
+ * @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;
+
+export { type EnvLayer as E, type InferEnvType as I, EnvRegistry as a, type EnvSchemaCollection as b, type EnvValidationResult as c, type EnvVarSchema as d, createEnvRegistry as e, defineEnvSchema as f, envBoolean as g, envEnum as h, envJson as i, envNumber as j, envSecret as k, envString as l, envUrl as m, isClientAccessible as n, isNextjsAccessible as o, isServerOnly as p, isSpfnServerOnly as q, validateAllEnv as v };

package/dist/server/index.d.ts

@@ -13,6 +13,7 @@ import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { R as RouteDef } from '../route-builder-2ani2jEI.js';
+import { a as EnvRegistry } from '../registry-DZHXQ134.js';
 import 'pg-boss';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono/utils/http-status';
@@ -553,6 +554,35 @@ interface ServerConfig {
          */
         allowPending?: boolean;
     };
+    /**
+     * Environment boot check
+     *
+     * Before serving, the server validates every variable of `@spfn/core`'s
+     * registry and of the registries listed here: a required variable must be
+     * set, and a set variable must pass its `validator`. On failure it logs
+     * each key with the reason — never a value — and refuses to start.
+     * `SKIP_ENV_VALIDATION` does not skip this check.
+     *
+     * @example
+     * ```typescript
+     * // src/server/config/env.config.ts
+     * export const envSchema = defineEnvSchema({ ... });
+     * export const envRegistry = createEnvRegistry(envSchema);
+     * export const env = envRegistry.validate();
+     *
+     * // src/server/server.config.ts
+     * export default defineServerConfig()
+     *     .env({ registries: [envRegistry] })
+     *     .build();
+     * ```
+     */
+    env?: {
+        /**
+         * Registries checked alongside `@spfn/core`'s: the app's own, and any
+         * package registry the app wants held to the same gate.
+         */
+        registries?: EnvRegistry<any>[];
+    };
     /**
      * Infrastructure initialization control
      * Controls automatic initialization of database and Redis
@@ -818,6 +848,8 @@ declare const CORE_TIME_PATH = "/_core/time";
  * Start SPFN server
  *
  * Automatically loads server.config.ts if exists
+ * Validates the environment (core's registry + `config.env.registries`) and
+ * exits with code 1 when a variable is missing or invalid
  * Automatically initializes Database and Redis from environment
  * Sets up graceful shutdown handlers for SIGTERM and SIGINT
  *
@@ -961,6 +993,9 @@ declare function getShutdownManager(): ShutdownManager;
  *   - does NOT run seed/RBAC provisioning per cold start — that moves to a
  *     deploy-time step, see {@link provisionInfrastructure}.
  *
+ * Like {@link startServer}, it runs the environment boot check before building
+ * the app; a failure rejects the returned promise instead of exiting.
+ *
  * `startServer()` / `spfn start` (the always-on path) is unchanged by this module.
  */
 
@@ -1284,6 +1319,22 @@ declare class ServerConfigBuilder {
      * ```
      */
     migrations(migrations: ServerConfig['migrations']): this;
+    /**
+     * Hand the app's env registries to the boot check
+     *
+     * `@spfn/core`'s own registry is always checked; the registries given here
+     * are checked with it, before the server listens.
+     *
+     * @example
+     * ```typescript
+     * import { envRegistry } from '@/server/config/env.config';
+     *
+     * export default defineServerConfig()
+     *     .env({ registries: [envRegistry] })
+     *     .build();
+     * ```
+     */
+    env(env: ServerConfig['env']): this;
     /**
      * Register workflow router for workflow orchestration
      *

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { env } from '@spfn/core/config';
+import { env, registry } from '@spfn/core/config';
 import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
 import { parse } from 'dotenv';
@@ -2880,6 +2880,50 @@ function readPort(value) {
   const port = Number(value);
   return Number.isInteger(port) && port > 0 && port < 65536 ? port : void 0;
 }
+logger.child("@spfn/core:env-registry");
+function validateAllEnv(registries) {
+  const errors = [];
+  const warnings = [];
+  for (const registry of registries) {
+    const result = registry.validateAll();
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+// src/server/env-boot-check.ts
+function runEnvBootCheck(config) {
+  const result = validateAllEnv([registry, ...config.env?.registries ?? []]);
+  const errors = uniqueByMessage(result.errors);
+  const warnings = uniqueByMessage(result.warnings);
+  for (const warning of warnings) {
+    serverLogger.warn(`Environment: ${warning.message}`);
+  }
+  if (errors.length > 0) {
+    serverLogger.error(
+      `Environment validation failed (${errors.length}):
+` + errors.map((error) => `  - ${error.message}`).join("\n")
+    );
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function uniqueByMessage(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  return entries.filter((entry) => {
+    const id = `${entry.key}
+${entry.message}`;
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
+}
 
 // src/server/validation.ts
 function validateServerConfig(config) {
@@ -2938,6 +2982,10 @@ var processHandlersRegistered = false;
 async function startServer(config) {
   loadEnv();
   const finalConfig = await loadAndMergeConfig(config);
+  if (!runEnvBootCheck(finalConfig).valid) {
+    serverLogger.error("Refusing to start: fix the environment variables listed above.");
+    process.exit(1);
+  }
   const { host, port, debug } = finalConfig;
   validateServerConfig(finalConfig);
   if (!host || !port) {
@@ -3428,6 +3476,9 @@ function createServerlessApp(config) {
 }
 async function buildServerlessApp(rawConfig) {
   loadEnv();
+  if (!runEnvBootCheck(rawConfig ?? {}).valid) {
+    throw new Error("Environment validation failed \u2014 the missing or invalid keys are logged above.");
+  }
   const config = withServerlessDefaults(rawConfig);
   warnIfJobsConfigured(config);
   await initInfrastructure(config);
@@ -3756,6 +3807,25 @@ var ServerConfigBuilder = class {
     this.config.migrations = migrations;
     return this;
   }
+  /**
+   * Hand the app's env registries to the boot check
+   *
+   * `@spfn/core`'s own registry is always checked; the registries given here
+   * are checked with it, before the server listens.
+   *
+   * @example
+   * ```typescript
+   * import { envRegistry } from '@/server/config/env.config';
+   *
+   * export default defineServerConfig()
+   *     .env({ registries: [envRegistry] })
+   *     .build();
+   * ```
+   */
+  env(env6) {
+    this.config.env = env6;
+    return this;
+  }
   /**
    * Register workflow router for workflow orchestration
    *