create-entity-app-server 0.0.3 → 0.1.13

package/src/system/startup-banner.ts

@@ -1,191 +0,0 @@
-import { env, isDev } from "./config/env.ts";
-import { serverConfig } from "./config/server.ts";
-import { loadCorsConfig } from "./config/cors.ts";
-import { loadSecurityJson } from "./config/security-loader.ts";
-import { loadDatabaseConfig } from "./config/database.ts";
-import { loadCacheConfig } from "./cache/config.ts";
-import { loadPasswordPolicy } from "./security/password-policy.ts";
-
-const ANSI = {
-    reset: "\u001b[0m",
-    cyan: "\u001b[96m",
-    green: "\u001b[92m",
-    pink: "\u001b[95m",
-    yellow: "\u001b[93m",
-} as const;
-
-const BANNER_WIDTH = 74;
-const BANNER_INNER_WIDTH = BANNER_WIDTH - 2;
-const BANNER_CONTENT_WIDTH = BANNER_INNER_WIDTH - 2;
-const ANSI_ESCAPE = /\u001b\[[0-9;]*m/g;
-
-export interface StartupSummary {
-    hookCount: number;
-    pluginCount: number;
-    routeCount: number;
-    scheduleCount: number;
-}
-
-function stripProtocol(text: string): string {
-    return text.replace(/^https?:\/\//, "");
-}
-
-function statusText(enabled: boolean): string {
-    return enabled ? color("enabled", ANSI.green) : "disabled";
-}
-
-function valueText(text: string): string {
-    return color(text, ANSI.pink);
-}
-
-function color(text: string, code: string): string {
-    return isDev ? `${code}${text}${ANSI.reset}` : text;
-}
-
-function visibleLength(text: string): number {
-    return text.replace(ANSI_ESCAPE, "").length;
-}
-
-function padRight(text: string, width: number): string {
-    const padding = Math.max(0, width - visibleLength(text));
-    return `${text}${" ".repeat(padding)}`;
-}
-
-function center(text: string, width: number): string {
-    const space = Math.max(0, width - visibleLength(text));
-    const left = Math.floor(space / 2);
-    const right = space - left;
-    return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
-}
-
-function line(content = ""): string {
-    return `${color("│", ANSI.cyan)} ${padRight(content, BANNER_CONTENT_WIDTH)} ${color("│", ANSI.cyan)}`;
-}
-
-function kvPart(label: string, value: string, width: number): string {
-    if (!label && !value) {
-        return " ".repeat(width);
-    }
-
-    if (!label) {
-        return padRight(value, width);
-    }
-
-    const base = `${label} ${value}`;
-    const baseLength = visibleLength(base);
-    if (baseLength >= width) {
-        return padRight(base, width);
-    }
-
-    const dotCount = Math.max(
-        1,
-        width - visibleLength(label) - visibleLength(value) - 2,
-    );
-    return `${label} ${".".repeat(dotCount)} ${value}`;
-}
-
-function kv(
-    leftLabel: string,
-    leftValue: string,
-    rightLabel: string,
-    rightValue: string,
-): string {
-    const separator = "  ";
-    const leftWidth = Math.floor((BANNER_CONTENT_WIDTH - separator.length) / 2);
-    const rightWidth = BANNER_CONTENT_WIDTH - separator.length - leftWidth;
-    return `${kvPart(leftLabel, leftValue, leftWidth)}${separator}${kvPart(rightLabel, rightValue, rightWidth)}`;
-}
-
-export function printStartupBanner(
-    listenUrl: string,
-    summary: StartupSummary,
-): void {
-    const publicUrl = serverConfig.baseUrl?.trim() || "-";
-    const cacheConfig = loadCacheConfig();
-    const corsConfig = loadCorsConfig();
-    const databaseConfig = loadDatabaseConfig();
-    const securityConfig = loadSecurityJson();
-    const passwordPolicy = loadPasswordPolicy();
-    const name = `${color("Entity App Server", ANSI.green)} ${color("ready", ANSI.yellow)}`;
-    const listenText = stripProtocol(listenUrl);
-    const entityText = stripProtocol(env.ENTITY_SERVER_URL);
-    const publicText = publicUrl === "-" ? publicUrl : stripProtocol(publicUrl);
-    const showPublicUrl =
-        publicText !== "-" &&
-        publicText !== listenText &&
-        publicText !== `${serverConfig.host}:${serverConfig.port}`;
-    const csrfEnabled = securityConfig.csrf?.enabled === true;
-    const packetEncryptEnabled =
-        securityConfig.packet_encrypt?.enabled === true;
-    const defaultDbGroup = databaseConfig?.groups[databaseConfig.default];
-    const databaseText = defaultDbGroup ? databaseConfig.default : "disabled";
-    const lines = [
-        color(`┌${"─".repeat(BANNER_INNER_WIDTH)}┐`, ANSI.cyan),
-        line(center(name, BANNER_CONTENT_WIDTH)),
-        line(),
-        line(center(color(listenText, ANSI.yellow), BANNER_CONTENT_WIDTH)),
-        line(
-            center(
-                color(`Entity Server: ${entityText}`, ANSI.yellow),
-                BANNER_CONTENT_WIDTH,
-            ),
-        ),
-        line(center(color(env.NODE_ENV, ANSI.yellow), BANNER_CONTENT_WIDTH)),
-        line(),
-        line(
-            kv(
-                "Namespace",
-                valueText(serverConfig.namespace),
-                "Log Level",
-                valueText(serverConfig.logging.level),
-            ),
-        ),
-        ...(showPublicUrl
-            ? [line(kv("", "", "Public URL", valueText(publicText)))]
-            : []),
-        line(
-            kv(
-                "CORS",
-                statusText(corsConfig.enabled),
-                "CSRF",
-                statusText(csrfEnabled),
-            ),
-        ),
-        line(
-            kv(
-                "Packet Encrypt",
-                statusText(packetEncryptEnabled),
-                "Password Policy",
-                statusText(passwordPolicy.enabled),
-            ),
-        ),
-        line(
-            kv(
-                "Cache",
-                valueText(cacheConfig.driver),
-                "Database",
-                valueText(databaseText),
-            ),
-        ),
-        line(),
-        line(
-            kv(
-                "Hooks",
-                valueText(String(summary.hookCount)),
-                "Plugins",
-                valueText(String(summary.pluginCount)),
-            ),
-        ),
-        line(
-            kv(
-                "Routes",
-                valueText(String(summary.routeCount)),
-                "Schedules",
-                valueText(String(summary.scheduleCount)),
-            ),
-        ),
-        color(`└${"─".repeat(BANNER_INNER_WIDTH)}┘`, ANSI.cyan),
-    ];
-
-    process.stdout.write(`${lines.join("\n")}\n`);
-}

package/src/system/types/fastify.d.ts

@@ -1,53 +0,0 @@
-/**
- * Fastify 타입 확장 — req.user, app.db, app.authRequired 등
- *
- * system → app 역참조 제거: app 레이어 타입은 generic/unknown 으로 선언하고
- * 실제 사용처에서 타입 단언(as)을 통해 구체 타입으로 변환한다.
- */
-
-import type { Kysely } from "kysely";
-import type { UserInfo } from "../hooks/types.ts";
-import type { CacheStore } from "../cache/types.ts";
-
-declare module "fastify" {
-    interface FastifyRequest {
-        /** JWT 디코드된 사용자 정보 (프록시: decode만, 비즈니스: verify 후) */
-        user: UserInfo | null;
-        /** 패킷 복호화된 raw body (packet-encrypt 플러그인이 주입) */
-        rawBody?: Buffer;
-        /** 패킷 암호화 키 — 요청이 암호화된 경우 응답 암호화에 사용 */
-        _packetKey?: Buffer;
-    }
-
-    interface FastifyInstance {
-        /** Kysely DB 인스턴스 — default 그룹 (database.json 미설정 시 null) */
-        db: Kysely<any> | null;
-
-        /** 모든 DB 그룹 커넥션 맵 (database.json groups 키 → Kysely 인스턴스) */
-        dbGroups: Record<string, Kysely<any>>;
-
-        /** 비즈니스 라우트 preHandler: JWT verify + 만료 확인 */
-        authRequired: (
-            req: import("fastify").FastifyRequest,
-            reply: import("fastify").FastifyReply,
-        ) => Promise<void>;
-
-        /** OCR 서비스 인스턴스 (disabled 시 null) — app.plugins.ocr 에서 등록 */
-        ocrService: unknown;
-
-        /** 본인인증 서비스 인스턴스 (disabled 시 null) — app.plugins.identity 에서 등록 */
-        identityService: unknown;
-
-        /** 공통 캐시 스토어 (driver: memory | redis, configs/cache.json 참고) */
-        cache: CacheStore;
-
-        /** 한국 선박 입항 서비스 인스턴스 (disabled 시 null) — app.plugins.vessel_kr 에서 등록 */
-        vesselKrService: unknown;
-
-        /** 코베코 운임지수 서비스 인스턴스 (disabled 시 null) — app.plugins.kobc_freight 에서 등록 */
-        kobcFreightService: unknown;
-
-        /** AIS 선박 위치 서비스 인스턴스 (disabled 시 null) — app.plugins.ais 에서 등록 */
-        aisService: unknown;
-    }
-}

package/src/system/utils/app-path.ts

@@ -1,31 +0,0 @@
-/**
- * app 디렉토리 경로 헬퍼
- *
- * system.js가 번들된 환경(prod)과 tsx로 직접 실행하는 환경(dev) 양쪽에서
- * app/ 디렉토리를 올바르게 찾아준다.
- *
- * 경로 기준:
- *   prod: dist/system.js  → import.meta.url 기준 base = dist/  → dist/app/ 존재
- *   dev:  src/system/**   → import.meta.url 기준 base = src/system/[subdir]/
- *                          → 2단계 상위(src/) + app = src/app/
- */
-
-import path from "path";
-import { existsSync } from "fs";
-import { fileURLToPath } from "url";
-
-/**
- * 호출 측의 import.meta.url을 전달하면 app/ 루트 절대경로를 반환한다.
- *
- * @param callerMetaUrl - 호출 파일의 import.meta.url
- */
-export function resolveAppRoot(callerMetaUrl: string): string {
-    const base = path.dirname(fileURLToPath(callerMetaUrl));
-
-    // prod: system.js (dist/) 기준 → dist/app 이 존재
-    const prodApp = path.join(base, "app");
-    if (existsSync(prodApp)) return prodApp;
-
-    // dev: src/system/[plugins|routes|hooks]/ 기준 → ../../app = src/app
-    return path.resolve(base, "..", "..", "app");
-}

package/src/system/utils/coerce.ts

@@ -1,28 +0,0 @@
-/**
- * 안전한 타입 변환 헬퍼
- *
- * unknown 값을 number, string 등으로 안전하게 변환한다.
- * pg, taxinvoice 등 여러 플러그인의 entity-adapter 에서 공통으로 사용.
- */
-
-/** unknown → number (null/NaN → 0) */
-export function toNumber(v: unknown): number {
-    if (v == null) return 0;
-    const n = Number(v);
-    return Number.isNaN(n) ? 0 : n;
-}
-
-/** unknown → string (null → "") */
-export function toString(v: unknown): string {
-    if (v == null) return "";
-    return String(v);
-}
-
-/** unknown → boolean (truthy 변환) */
-export function toBool(v: unknown): boolean {
-    if (v == null) return false;
-    if (typeof v === "string") {
-        return v === "true" || v === "1" || v === "yes";
-    }
-    return Boolean(v);
-}

package/src/system/utils/date-prefixed-log-stream.ts

@@ -1,176 +0,0 @@
-import {
-    createWriteStream,
-    mkdirSync,
-    readdirSync,
-    rmSync,
-    type WriteStream,
-} from "fs";
-import path from "path";
-import { Writable } from "stream";
-
-type RotationFrequency = "daily" | "hourly";
-
-type DatePrefixedLogStreamOptions = {
-    logDir: string;
-    filename: string;
-    frequency: RotationFrequency;
-    maxFiles: number;
-};
-
-/** 로그 파일명을 `.log` 확장자를 포함한 표준 형식으로 정규화합니다. */
-function normalizeFilename(filename: string): string {
-    const trimmed = filename.trim();
-    if (!trimmed) {
-        return "app.log";
-    }
-    return trimmed.endsWith(".log") ? trimmed : `${trimmed}.log`;
-}
-
-/** 현재 시각과 회전 주기에 맞는 파일 접두 키를 생성합니다. */
-function makePeriodKey(date: Date, frequency: RotationFrequency): string {
-    const year = String(date.getFullYear());
-    const month = String(date.getMonth() + 1).padStart(2, "0");
-    const day = String(date.getDate()).padStart(2, "0");
-    if (frequency === "hourly") {
-        const hour = String(date.getHours()).padStart(2, "0");
-        return `${year}-${month}-${day}-${hour}`;
-    }
-    return `${year}-${month}-${day}`;
-}
-
-/** 접두 날짜 키와 원본 파일명으로 실제 로그 파일명을 구성합니다. */
-function buildLogFilename(periodKey: string, filename: string): string {
-    return `${periodKey}.${normalizeFilename(filename)}`;
-}
-
-/** 로그 파일명에서 회전 주기에 해당하는 날짜 키를 추출합니다. */
-function extractPeriodKey(
-    name: string,
-    frequency: RotationFrequency,
-): string | null {
-    const match =
-        frequency === "hourly"
-            ? name.match(/^(\d{4}-\d{2}-\d{2}-\d{2})\./)
-            : name.match(/^(\d{4}-\d{2}-\d{2})\./);
-    return match?.[1] ?? null;
-}
-
-/** 날짜 접두 기반 로그 로테이션과 보관 개수 정리를 담당하는 Writable 스트림입니다. */
-export class DatePrefixedLogStream extends Writable {
-    private readonly logDir: string;
-    private readonly filename: string;
-    private readonly frequency: RotationFrequency;
-    private readonly maxFiles: number;
-    private currentKey = "";
-    private currentStream: WriteStream | null = null;
-
-    constructor(options: DatePrefixedLogStreamOptions) {
-        super();
-        this.logDir = path.resolve(options.logDir);
-        this.filename = normalizeFilename(options.filename);
-        this.frequency = options.frequency;
-        this.maxFiles = Math.max(1, options.maxFiles);
-        mkdirSync(this.logDir, { recursive: true });
-    }
-
-    /** 현재 회전 파일 스트림에 로그 청크를 기록합니다. */
-    override _write(
-        chunk: Buffer | string,
-        encoding: BufferEncoding,
-        callback: (error?: Error | null) => void,
-    ): void {
-        try {
-            this.ensureStream();
-            if (!this.currentStream) {
-                callback();
-                return;
-            }
-
-            this.currentStream.write(chunk, encoding, callback);
-        } catch (error) {
-            callback(error as Error);
-        }
-    }
-
-    /** 스트림 종료 시 현재 열려 있는 로그 파일을 안전하게 닫습니다. */
-    override _final(callback: (error?: Error | null) => void): void {
-        if (!this.currentStream) {
-            callback();
-            return;
-        }
-
-        const stream = this.currentStream;
-        this.currentStream = null;
-        this.currentKey = "";
-        stream.end(() => callback());
-    }
-
-    /** 스트림 파기 시 현재 로그 파일 핸들을 정리합니다. */
-    override _destroy(
-        error: Error | null,
-        callback: (error?: Error | null) => void,
-    ): void {
-        if (!this.currentStream) {
-            callback(error);
-            return;
-        }
-
-        const stream = this.currentStream;
-        this.currentStream = null;
-        this.currentKey = "";
-        stream.end(() => callback(error));
-    }
-
-    /** 현재 시점에 맞는 로그 파일이 열려 있는지 확인하고 필요하면 교체합니다. */
-    private ensureStream(): void {
-        const nextKey = makePeriodKey(new Date(), this.frequency);
-        if (this.currentStream && this.currentKey === nextKey) {
-            return;
-        }
-
-        if (this.currentStream) {
-            this.currentStream.end();
-        }
-
-        const filePath = path.join(
-            this.logDir,
-            buildLogFilename(nextKey, this.filename),
-        );
-
-        this.currentStream = createWriteStream(filePath, { flags: "a" });
-        this.currentKey = nextKey;
-        this.pruneOldFiles();
-    }
-
-    /** 보관 개수를 초과한 오래된 로그 파일을 삭제합니다. */
-    private pruneOldFiles(): void {
-        const matched = readdirSync(this.logDir)
-            .filter((name) => name.endsWith(`.${this.filename}`))
-            .map((name) => ({
-                name,
-                key: extractPeriodKey(name, this.frequency),
-            }))
-            .filter(
-                (entry): entry is { name: string; key: string } =>
-                    entry.key !== null,
-            )
-            .sort((left, right) => right.key.localeCompare(left.key));
-
-        const stale = matched.slice(this.maxFiles);
-        for (const entry of stale) {
-            try {
-                const filePath = path.join(this.logDir, entry.name);
-                rmSync(filePath, { force: true });
-            } catch {
-                // ignore prune failures
-            }
-        }
-    }
-}
-
-/** 날짜 접두 기반 로그 스트림 인스턴스를 생성합니다. */
-export function createDatePrefixedLogStream(
-    options: DatePrefixedLogStreamOptions,
-): DatePrefixedLogStream {
-    return new DatePrefixedLogStream(options);
-}

package/src/system/utils/errors.ts

@@ -1,66 +0,0 @@
-/**
- * 커스텀 에러 클래스
- */
-
-/** 애플리케이션 공통 베이스 에러입니다. */
-export class AppError extends Error {
-    constructor(
-        message: string,
-        public readonly statusCode: number = 500,
-        public readonly code?: string,
-    ) {
-        super(message);
-        this.name = "AppError";
-    }
-}
-
-/** 잘못된 요청 입력을 나타내는 400 에러입니다. */
-export class BadRequestError extends AppError {
-    constructor(message = "Bad Request") {
-        super(message, 400, "BAD_REQUEST");
-        this.name = "BadRequestError";
-    }
-}
-
-/** 인증 실패를 나타내는 401 에러입니다. */
-export class UnauthorizedError extends AppError {
-    constructor(message = "Unauthorized") {
-        super(message, 401, "UNAUTHORIZED");
-        this.name = "UnauthorizedError";
-    }
-}
-
-/** 권한 부족을 나타내는 403 에러입니다. */
-export class ForbiddenError extends AppError {
-    constructor(message = "Forbidden") {
-        super(message, 403, "FORBIDDEN");
-        this.name = "ForbiddenError";
-    }
-}
-
-/** 리소스를 찾지 못했음을 나타내는 404 에러입니다. */
-export class NotFoundError extends AppError {
-    constructor(message = "Not Found") {
-        super(message, 404, "NOT_FOUND");
-        this.name = "NotFoundError";
-    }
-}
-
-/** 리소스 충돌을 나타내는 409 에러입니다. */
-export class ConflictError extends AppError {
-    constructor(message = "Conflict") {
-        super(message, 409, "CONFLICT");
-        this.name = "ConflictError";
-    }
-}
-
-/** 유효성 검증 실패 상세를 담는 422 에러입니다. */
-export class ValidationError extends AppError {
-    constructor(
-        message = "Validation Error",
-        public readonly details?: unknown,
-    ) {
-        super(message, 422, "VALIDATION_ERROR");
-        this.name = "ValidationError";
-    }
-}

package/src/system/utils/format.ts

@@ -1,45 +0,0 @@
-/**
- * 문자열 포맷팅 유틸리티
- *
- * 전화번호, 사업자번호, 날짜 등 반복되는 포맷 변환을
- * 플러그인(SMS, OCR, Identity, TaxInvoice)에서 공유한다.
- */
-
-/** 문자열에서 숫자만 추출한다 */
-export function extractDigits(s: string): string {
-    return s.replace(/[^0-9]/g, "");
-}
-
-/** Date 값을 SQL datetime 문자열(YYYY-MM-DD HH:mm:ss)로 변환한다. */
-export function formatSqlDateTime(date: Date = new Date()): string {
-    return date.toISOString().replace("T", " ").replace("Z", "").slice(0, 19);
-}
-
-/**
- * 한국 전화번호를 E.164 형식으로 변환한다.
- *
- * - "01012345678"  → "+821012345678" (0 제거 + 82 추가)
- * - "+821012345678" → 그대로
- *
- * @param phone    전화번호 문자열
- * @param country  국가 코드 (기본 "82")
- */
-export function normalizePhoneE164(phone: string, country = "82"): string {
-    if (phone.startsWith("+")) return phone;
-    const cleaned = extractDigits(phone);
-    if (cleaned.startsWith("0")) {
-        return `+${country}${cleaned.slice(1)}`;
-    }
-    return `+${cleaned}`;
-}
-
-/**
- * 사업자번호를 NNN-NN-NNNNN 형식으로 정규화한다.
- *
- * "1234567890" → "123-45-67890"
- */
-export function formatBizNum(raw: string): string {
-    const digits = extractDigits(raw);
-    if (digits.length !== 10) return raw;
-    return `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5)}`;
-}

package/src/system/utils/http-client.ts

@@ -1,79 +0,0 @@
-/**
- * HTTP 클라이언트 헬퍼 — fetch + 타임아웃 + 에러 처리
- *
- * 모든 외부 API provider (SMS, PG, TaxInvoice, Identity, Holidays 등)에서
- * 반복되는 fetch + AbortController + setTimeout 패턴을 통합한다.
- */
-
-export interface FetchOptions extends Omit<RequestInit, "signal"> {
-    /** 요청 타임아웃 (ms). 기본: 30000 */
-    timeoutMs?: number;
-}
-
-export interface FetchResult<T = unknown> {
-    ok: boolean;
-    status: number;
-    data: T;
-    headers: Headers;
-}
-
-/**
- * 타임아웃 지원 fetch 래퍼.
- * 지정된 시간 내 응답이 없으면 AbortError 를 throw 한다.
- *
- * @param url     요청 URL
- * @param options fetch 옵션 + timeoutMs
- * @returns       FetchResult (JSON 파싱 시도, 실패 시 text)
- */
-export async function fetchWithTimeout<T = unknown>(
-    url: string,
-    options: FetchOptions = {},
-): Promise<FetchResult<T>> {
-    const { timeoutMs = 30_000, ...fetchOpts } = options;
-
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-        const response = await fetch(url, {
-            ...fetchOpts,
-            signal: controller.signal,
-        });
-
-        let data: T;
-        const contentType = response.headers.get("content-type") ?? "";
-        if (contentType.includes("application/json")) {
-            data = (await response.json()) as T;
-        } else {
-            data = (await response.text()) as unknown as T;
-        }
-
-        return {
-            ok: response.ok,
-            status: response.status,
-            data,
-            headers: response.headers,
-        };
-    } finally {
-        clearTimeout(timer);
-    }
-}
-
-/**
- * JSON POST 요청을 공통 헤더와 함께 전송합니다.
- */
-export function fetchJson<T = unknown>(
-    url: string,
-    body: unknown,
-    options: FetchOptions = {},
-): Promise<FetchResult<T>> {
-    return fetchWithTimeout<T>(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            ...((options.headers as Record<string, string>) ?? {}),
-        },
-        body: JSON.stringify(body),
-        ...options,
-    });
-}