@gaonjs/core 0.1.3 → 0.1.4

package/dist/env.d.ts

@@ -0,0 +1,60 @@
+/**
+ * env 누락·형변환 실패를 알리는 에러. 메시지가 곧 수리 안내서다
+ * (§7.5.3 — "무엇이 잘못됐다"가 아니라 "→ 어디에 무엇을 추가하라"까지).
+ */
+export declare class EnvError extends Error {
+    constructor(message: string);
+}
+/**
+ * `.env` 파일을 로드한다. NODE_ENV 별 오버레이(`.env.<env>`)를 나중에 얹어
+ * 우선하게 한다(이미 정의된 process.env 는 loadEnvFile 이 덮지 않는다 —
+ * 실제 환경변수가 파일보다 우선). 파일이 없으면 조용히 지나간다.
+ *
+ * `gaon dev`·`gaon serve`·`gaon work` 부팅 진입점이 가장 먼저 호출한다.
+ */
+export declare function loadDotEnv(root?: string): void;
+/** 옵션 없는 문자열 env — 필수. 누락 시 EnvError(수리 안내). */
+export interface RequiredOpts {
+    readonly default?: undefined;
+}
+/** 기본값이 있는 문자열 env — 누락 시 default. */
+export interface DefaultedOpts {
+    readonly default: string;
+}
+export interface EnvHelper {
+    /** 필수 문자열. 누락 시 부팅 에러. */
+    (key: string): string;
+    /** 기본값이 있는 문자열. 누락 시 default. */
+    (key: string, opts: DefaultedOpts): string;
+    /** 선택 문자열 — 누락 시 undefined(EnvError 없음). */
+    optional(key: string): string | undefined;
+    /** 정수. 파싱 실패 시 EnvError. default 로 누락 허용. */
+    int(key: string, opts?: {
+        default?: number;
+    }): number;
+    /** 불리언. `1·true·yes·on`(대소문자 무시) = true. default 로 누락 허용. */
+    bool(key: string, opts?: {
+        default?: boolean;
+    }): boolean;
+    /** 콤마 구분 문자열 목록. 누락 시 default(생략 시 []). */
+    list(key: string, opts?: {
+        default?: readonly string[];
+    }): string[];
+}
+/**
+ * 타입 안전 env 헬퍼. `gaon.config.ts` 등 부팅 경로에서 호출한다 —
+ * 최상위에서 호출하면 선언된 env 누락이 **부팅 시점**에 드러난다(§7).
+ *
+ *   env('DATABASE_URL')                  // 필수 문자열
+ *   env('PORT', { default: '3000' })     // 기본값
+ *   env.int('WEB_CONCURRENCY', { default: 1 })
+ *   env.bool('DEBUG', { default: false })
+ *   env.optional('SENTRY_DSN')           // string | undefined
+ */
+export declare const env: EnvHelper;
+/**
+ * 여러 필수 env 를 한 번에 검증한다 — 누락을 **모아서** 한 에러로 보고해
+ * "고치고 재시작 → 또 다른 누락" 반복을 없앤다. 부팅 진입점에서 선언 목록을
+ * 넘겨 호출한다.
+ */
+export declare function requireEnv(keys: readonly string[]): void;

package/dist/env.js

@@ -0,0 +1,125 @@
+// @gaonjs/core · 환경변수/시크릿 배터리 (§7 v0.14 편입)
+//
+// `.env` 관례로 값을 싣고, `env('KEY')` 타입 안전 헬퍼로 읽는다. 선언된
+// env 가 누락되면 **부팅 시점**에 수리 안내를 포함한 에러로 즉시 실패한다
+// (런타임 한복판에서 터지지 않게). 시크릿은 env 로만 주입한다 — 코드·설정
+// 파일 하드코딩은 doctor 가 검사한다.
+//
+// dotenv 대신 Node 22+ 내장 `process.loadEnvFile()` 를 쓴다(engines ≥22).
+// 신규 의존을 늘리지 않는다는 원칙(§0)과, "만들지 않고 접착한다"(§2)에 맞다.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * env 누락·형변환 실패를 알리는 에러. 메시지가 곧 수리 안내서다
+ * (§7.5.3 — "무엇이 잘못됐다"가 아니라 "→ 어디에 무엇을 추가하라"까지).
+ */
+export class EnvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvError';
+    }
+}
+function repairHint(key, reason) {
+    return (`환경변수 ${key} ${reason}\n` +
+        `  → 프로젝트 루트 .env 에 다음 줄을 추가하고 프로세스를 재시작하세요:\n` +
+        `      ${key}=<값>\n` +
+        `    (예시는 .env.example 을 참고. 시크릿은 코드·설정 파일에 하드코딩하지 마세요.)`);
+}
+/**
+ * `.env` 파일을 로드한다. NODE_ENV 별 오버레이(`.env.<env>`)를 나중에 얹어
+ * 우선하게 한다(이미 정의된 process.env 는 loadEnvFile 이 덮지 않는다 —
+ * 실제 환경변수가 파일보다 우선). 파일이 없으면 조용히 지나간다.
+ *
+ * `gaon dev`·`gaon serve`·`gaon work` 부팅 진입점이 가장 먼저 호출한다.
+ */
+export function loadDotEnv(root = process.cwd()) {
+    const nodeEnv = process.env.NODE_ENV;
+    // 환경별 오버레이를 먼저 로드해 우선순위를 준다: loadEnvFile 은 이미
+    // 설정된 키를 덮지 않으므로, 더 구체적인 파일을 앞서 로드한다.
+    if (nodeEnv) {
+        const envFile = join(root, `.env.${nodeEnv}`);
+        if (existsSync(envFile))
+            process.loadEnvFile(envFile);
+    }
+    const base = join(root, '.env');
+    if (existsSync(base))
+        process.loadEnvFile(base);
+}
+function raw(key) {
+    const v = process.env[key];
+    // 빈 문자열은 "미설정"으로 취급한다 — `.env` 에 `KEY=` 만 적힌 흔한 실수가
+    // 조용히 통과해 런타임에서 터지는 것을 부팅 시점 에러로 앞당긴다.
+    return v === undefined || v === '' ? undefined : v;
+}
+function required(key) {
+    const v = raw(key);
+    if (v === undefined)
+        throw new EnvError(repairHint(key, '가 설정되지 않았습니다.'));
+    return v;
+}
+const base = ((key, opts) => {
+    const v = raw(key);
+    if (v !== undefined)
+        return v;
+    if (opts && 'default' in opts && opts.default !== undefined)
+        return opts.default;
+    return required(key);
+});
+base.optional = (key) => raw(key);
+base.int = (key, opts) => {
+    const v = raw(key);
+    if (v === undefined) {
+        if (opts && opts.default !== undefined)
+            return opts.default;
+        throw new EnvError(repairHint(key, '가 설정되지 않았습니다(정수 필요).'));
+    }
+    const n = Number(v);
+    if (!Number.isInteger(n)) {
+        throw new EnvError(repairHint(key, `= "${v}" 는 정수가 아닙니다.`));
+    }
+    return n;
+};
+base.bool = (key, opts) => {
+    const v = raw(key);
+    if (v === undefined) {
+        if (opts && opts.default !== undefined)
+            return opts.default;
+        throw new EnvError(repairHint(key, '가 설정되지 않았습니다(불리언 필요).'));
+    }
+    return ['1', 'true', 'yes', 'on'].includes(v.toLowerCase());
+};
+base.list = (key, opts) => {
+    const v = raw(key);
+    if (v === undefined)
+        return opts?.default ? [...opts.default] : [];
+    return v
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+};
+/**
+ * 타입 안전 env 헬퍼. `gaon.config.ts` 등 부팅 경로에서 호출한다 —
+ * 최상위에서 호출하면 선언된 env 누락이 **부팅 시점**에 드러난다(§7).
+ *
+ *   env('DATABASE_URL')                  // 필수 문자열
+ *   env('PORT', { default: '3000' })     // 기본값
+ *   env.int('WEB_CONCURRENCY', { default: 1 })
+ *   env.bool('DEBUG', { default: false })
+ *   env.optional('SENTRY_DSN')           // string | undefined
+ */
+export const env = base;
+/**
+ * 여러 필수 env 를 한 번에 검증한다 — 누락을 **모아서** 한 에러로 보고해
+ * "고치고 재시작 → 또 다른 누락" 반복을 없앤다. 부팅 진입점에서 선언 목록을
+ * 넘겨 호출한다.
+ */
+export function requireEnv(keys) {
+    const missing = keys.filter((k) => raw(k) === undefined);
+    if (missing.length === 0)
+        return;
+    const lines = missing.map((k) => `      ${k}=<값>`).join('\n');
+    throw new EnvError(`필수 환경변수 ${missing.length}개가 누락되었습니다: ${missing.join(', ')}\n` +
+        `  → 프로젝트 루트 .env 에 다음 줄을 추가하고 프로세스를 재시작하세요:\n` +
+        lines +
+        `\n    (.env.example 참고. 시크릿은 코드·설정 파일에 하드코딩하지 마세요.)`);
+}

package/dist/index.d.ts

@@ -27,3 +27,5 @@ export type IsHidden<V> = "__gaon_hidden__" extends keyof V ? true : false;
  * 전역 심볼 레지스트리(`Symbol.for`)라 패키지·번들 경계를 넘어도 동일하다.
  */
 export declare const HIDDEN_COLUMNS: unique symbol;
+export { env, loadDotEnv, requireEnv, EnvError, type EnvHelper, } from "./env.js";
+export { log, rootLogger, setRootLogger, runWithLogContext, enterLogContext, currentLogContext, type Logger, type LogContext, } from "./logging.js";

package/dist/index.js

@@ -26,3 +26,8 @@ export const MILESTONES = [
  * 전역 심볼 레지스트리(`Symbol.for`)라 패키지·번들 경계를 넘어도 동일하다.
  */
 export const HIDDEN_COLUMNS = Symbol.for("gaon.hiddenColumns");
+// ── 배터리 (§7 M8) ──────────────────────────────────────────────
+// env·구조화 로깅은 코어에 내장한다 — 어느 프로세스(웹·워커·허브)에서든
+// 같은 헬퍼를 쓴다. 시드/메일/스토리지/i18n 은 각자 패키지로 분리한다.
+export { env, loadDotEnv, requireEnv, EnvError, } from "./env.js";
+export { log, rootLogger, setRootLogger, runWithLogContext, enterLogContext, currentLogContext, } from "./logging.js";

package/dist/logging.d.ts

@@ -0,0 +1,41 @@
+import { type Logger as PinoLogger } from 'pino';
+/** 로그 컨텍스트 — 요청/잡/이벤트 경계에서 심어 하위 로그에 자동 전파된다. */
+export interface LogContext {
+    /** 요청/잡/이벤트 상관관계 ID. HTTP 요청·잡 실행·이벤트 처리마다 부여. */
+    readonly requestId?: string;
+    /** 추가 상관 필드(잡 이름·이벤트명 등). 로그에 그대로 병합된다. */
+    readonly [key: string]: unknown;
+}
+/** 현재 로그 컨텍스트를 읽는다(없으면 undefined). */
+export declare function currentLogContext(): LogContext | undefined;
+/**
+ * 주어진 컨텍스트로 fn 을 실행한다 — 그 안의 모든 로그에 컨텍스트 필드가
+ * 자동으로 붙는다(요청 ID 전파). 중첩 시 바깥 컨텍스트에 병합한다.
+ */
+export declare function runWithLogContext<T>(context: LogContext, fn: () => T): T;
+/**
+ * 콜백 없이 현재 비동기 컨텍스트에 로그 컨텍스트를 심는다(enterWith). Fastify
+ * onRequest 훅처럼 "이 지점 이후"의 모든 후속 처리에 요청 ID 를 전파해야 할
+ * 때 쓴다 — 이후 같은 요청의 모든 log.* 호출에 자동으로 붙는다.
+ */
+export declare function enterLogContext(context: LogContext): void;
+/** log.info(msg, fields) 형태의 어디서나 쓰는 로그 헬퍼(§7). */
+export interface Logger {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+    debug(message: string, fields?: Record<string, unknown>): void;
+    /** 고정 필드가 붙은 하위 로거(모듈·앱 스코프 등). */
+    child(fields: Record<string, unknown>): Logger;
+    /** 하위 통합(Fastify 등)이 요구하는 원시 pino 인스턴스. */
+    readonly raw: PinoLogger;
+}
+/** 프로세스 루트 로거(지연 초기화 — NODE_ENV·GAON_LOG_LEVEL 를 부팅 후 읽게). */
+export declare function rootLogger(): PinoLogger;
+/**
+ * 테스트/부팅에서 루트 로거를 명시 주입한다(요청별 재구성 방지·조용한 모드).
+ * 웹 앱은 Fastify 의 pino 인스턴스를 여기 심어 로거를 하나로 통일한다.
+ */
+export declare function setRootLogger(p: PinoLogger): void;
+/** 어디서나 쓰는 전역 로거. 컨텍스트(요청 ID)는 자동 전파된다(§7). */
+export declare const log: Logger;

package/dist/logging.js

@@ -0,0 +1,112 @@
+// @gaonjs/core · 구조화 로깅 배터리 (§7 v0.14 편입)
+//
+// JSON 구조화 로그를 코어에 내장한다. 요청(HTTP)·잡·이벤트 처리는 자동으로
+// 로그가 남고(요청 ID 전파 포함), 개발 모드는 사람이 읽는 포맷, 운영은 JSON.
+// `log.info(msg, fields)` 헬퍼를 어디서든 쓴다.
+//
+// pino 를 접착한다(§2 — 만들지 않고 접착) — Fastify 가 이미 pino 10 을 쓰므로
+// 웹·워커 전 프로세스에서 로거가 하나로 통일된다. 요청 ID 는
+// AsyncLocalStorage 로 전파하고, pino mixin 이 매 로그에 자동으로 얹는다.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createRequire } from 'node:module';
+import pino from 'pino';
+const contextStore = new AsyncLocalStorage();
+/** 현재 로그 컨텍스트를 읽는다(없으면 undefined). */
+export function currentLogContext() {
+    return contextStore.getStore();
+}
+/**
+ * 주어진 컨텍스트로 fn 을 실행한다 — 그 안의 모든 로그에 컨텍스트 필드가
+ * 자동으로 붙는다(요청 ID 전파). 중첩 시 바깥 컨텍스트에 병합한다.
+ */
+export function runWithLogContext(context, fn) {
+    const parent = contextStore.getStore();
+    return contextStore.run({ ...parent, ...context }, fn);
+}
+/**
+ * 콜백 없이 현재 비동기 컨텍스트에 로그 컨텍스트를 심는다(enterWith). Fastify
+ * onRequest 훅처럼 "이 지점 이후"의 모든 후속 처리에 요청 ID 를 전파해야 할
+ * 때 쓴다 — 이후 같은 요청의 모든 log.* 호출에 자동으로 붙는다.
+ */
+export function enterLogContext(context) {
+    const parent = contextStore.getStore();
+    contextStore.enterWith({ ...parent, ...context });
+}
+function isProd() {
+    return process.env.NODE_ENV === 'production';
+}
+/** pino-pretty 가 이 프로세스에서 해석 가능한지(설치 여부). 없으면 JSON 폴백. */
+function prettyAvailable() {
+    try {
+        createRequire(import.meta.url).resolve('pino-pretty');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultLevel() {
+    if (process.env.GAON_LOG_LEVEL)
+        return process.env.GAON_LOG_LEVEL;
+    // 테스트는 조용히(로깅 동작은 캡처 로거로 별도 검증) — 운영 info, 그 외 debug.
+    if (process.env.NODE_ENV === 'test')
+        return 'silent';
+    return isProd() ? 'info' : 'debug';
+}
+function createPino() {
+    const level = defaultLevel();
+    // 컨텍스트(요청 ID 등)를 매 로그에 병합한다 — pino mixin 은 로그 시점에
+    // 호출되므로 AsyncLocalStorage 의 현재 값을 그대로 실을 수 있다.
+    const mixin = () => contextStore.getStore() ?? {};
+    // 개발 모드는 사람이 읽는 포맷(pino-pretty), 그 외(운영·테스트)는 JSON 한
+    // 줄. pretty 는 워커 스레드 transport 라 (1)명시적 development 이고
+    // (2)pino-pretty 가 해석될 때만 켠다 — 테스트(NODE_ENV=test)·미설치
+    // 환경에서 코어가 죽지 않게 JSON 으로 폴백한다.
+    if (process.env.NODE_ENV === 'development' && prettyAvailable()) {
+        return pino({
+            level,
+            mixin,
+            transport: {
+                target: 'pino-pretty',
+                options: { colorize: true, translateTime: 'HH:MM:ss.l', ignore: 'pid,hostname' },
+            },
+        });
+    }
+    return pino({ level, mixin });
+}
+function wrap(p) {
+    return {
+        // pino 네이티브는 (mergingObject, message) 순서이므로 (msg, fields)를 뒤집는다.
+        info: (message, fields) => p.info(fields ?? {}, message),
+        warn: (message, fields) => p.warn(fields ?? {}, message),
+        error: (message, fields) => p.error(fields ?? {}, message),
+        debug: (message, fields) => p.debug(fields ?? {}, message),
+        child: (fields) => wrap(p.child(fields)),
+        raw: p,
+    };
+}
+let rootPino;
+/** 프로세스 루트 로거(지연 초기화 — NODE_ENV·GAON_LOG_LEVEL 를 부팅 후 읽게). */
+export function rootLogger() {
+    if (!rootPino)
+        rootPino = createPino();
+    return rootPino;
+}
+/**
+ * 테스트/부팅에서 루트 로거를 명시 주입한다(요청별 재구성 방지·조용한 모드).
+ * 웹 앱은 Fastify 의 pino 인스턴스를 여기 심어 로거를 하나로 통일한다.
+ */
+export function setRootLogger(p) {
+    rootPino = p;
+}
+/** 어디서나 쓰는 전역 로거. 컨텍스트(요청 ID)는 자동 전파된다(§7). */
+export const log = {
+    info: (m, f) => wrap(rootLogger()).info(m, f),
+    warn: (m, f) => wrap(rootLogger()).warn(m, f),
+    error: (m, f) => wrap(rootLogger()).error(m, f),
+    debug: (m, f) => wrap(rootLogger()).debug(m, f),
+    child: (f) => wrap(rootLogger().child(f)),
+    get raw() {
+        return rootLogger();
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Gaon 커널: 설정·생명주기·플러그인 시스템·doctor (M2+ 구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,12 @@
     "dist",
     "README.md"
   ],
+  "dependencies": {
+    "pino": "^10.3.1"
+  },
+  "devDependencies": {
+    "pino-pretty": "^13.1.3"
+  },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"
   }