create-entity-app-server 0.0.3

package/src/system/crypto/random.ts

@@ -0,0 +1,19 @@
+/**
+ * 암호학적 난수 유틸리티 — 인증코드, 토큰 생성 등
+ *
+ * 참고: 해시 함수는 crypto/hash.ts, 암복호화는 crypto/cipher.ts 를 사용한다.
+ */
+
+import { randomInt } from "node:crypto";
+
+/**
+ * 숫자 인증 코드를 생성한다.
+ *
+ * @param length 코드 자릿수 (기본 6)
+ * @returns 지정 자릿수의 숫자 문자열 (예: "183927")
+ */
+export function generateVerificationCode(length = 6): string {
+    const min = Math.pow(10, length - 1);
+    const max = Math.pow(10, length);
+    return String(randomInt(min, max));
+}

package/src/system/email/sender.ts

@@ -0,0 +1,85 @@
+/**
+ * SMTP 발송 유틸리티
+ *
+ * 게이트웨이에서 엔티티서버 SMTP API (/v1/smtp/send)를 경유하여 이메일을 발송한다.
+ * 로컬 템플릿 렌더링 후 body_html을 전달하거나,
+ * 엔티티서버 측 템플릿을 사용할 수도 있다.
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import { renderTemplate } from "./template-engine.ts";
+
+export interface SendEmailParams {
+    /** 수신자 이메일 (1개 이상 필수) */
+    to: string[];
+    /** 제목 */
+    subject: string;
+    /** 게이트웨이 로컬 템플릿명 (확장자 제외) */
+    templateName?: string;
+    /** 템플릿 파일이 위치한 절대경로 디렉토리 (미지정 시 전역 setTemplateDir 사용) */
+    templateDir?: string;
+    /** 템플릿 변수 */
+    templateData?: Record<string, unknown>;
+    /** 직접 HTML 본문 (templateName 대신 사용) */
+    bodyHtml?: string;
+    /** 텍스트 본문 */
+    bodyText?: string;
+    /** CC */
+    cc?: string[];
+    /** BCC */
+    bcc?: string[];
+    /** 발신자 */
+    from?: string;
+    /** Reply-To */
+    replyTo?: string;
+    /** 참조 엔티티 */
+    refEntity?: string;
+    /** 참조 seq */
+    refSeq?: number;
+}
+
+/**
+ * 이메일을 발송한다.
+ *
+ * templateName이 지정되면 게이트웨이 로컬 템플릿을 렌더링하여 body_html로 전달.
+ * bodyHtml이 직접 지정되면 그대로 전달.
+ *
+ * @returns 발송 큐 등록 seq
+ */
+export async function sendEmail(params: SendEmailParams): Promise<number> {
+    let html = params.bodyHtml ?? "";
+
+    // 로컬 템플릿 렌더링
+    if (params.templateName) {
+        const rendered = renderTemplate(
+            params.templateName,
+            params.templateData ?? {},
+            params.templateDir,
+        );
+        if (!rendered) {
+            logger.error(
+                { template: params.templateName },
+                "Email template rendering failed",
+            );
+            throw new Error(
+                `Email template not found: ${params.templateName}`,
+            );
+        }
+        html = rendered;
+    }
+
+    const resp = await entityServer.smtpSend({
+        to: params.to,
+        subject: params.subject,
+        body_html: html || undefined,
+        body_text: params.bodyText,
+        cc: params.cc,
+        bcc: params.bcc,
+        from: params.from,
+        reply_to: params.replyTo,
+        ref_entity: params.refEntity,
+        ref_seq: params.refSeq,
+    });
+
+    return resp.seq ?? 0;
+}

package/src/system/email/template-engine.ts

@@ -0,0 +1,147 @@
+/**
+ * 이메일 템플릿 엔진
+ *
+ * Go 엔티티서버 `internal/smtp/template.go`에서 포팅.
+ *
+ * 기능:
+ *  - `${variable}` 패턴 치환 (Go 동일 정규식)
+ *  - `${variable|기본값}` 폴백 지원
+ *  - 공유 레이아웃 래핑 — plugins/smtp/templates/layout.html 단일 파일로 관리
+ *    (setSharedLayout 으로 초기화, smtp 플러그인이 앱 시작 시 자동 호출)
+ *  - 파일 일회 로드 + 인메모리 캐시
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { logger } from "@gateway/api";
+
+/** 변수 치환 정규식: ${key} 또는 ${key|default} */
+const VAR_PATTERN = /\$\{([^}|]+?)(?:\|([^}]*))?\}/g;
+
+/** 템플릿 파일 캐시 (key: 절대경로 또는 `dir|name`, value: HTML 문자열) */
+const cache = new Map<string, string>();
+
+/** 템플릿 루트 디렉토리 */
+let templateDir = "";
+
+/** 공유 레이아웃 절대 파일 경로 */
+let sharedLayoutPath = "";
+
+/**
+ * 공유 레이아웃 파일 경로를 설정한다.
+ * smtp 플러그인(plugins/smtp/index.ts)이 앱 시작 시 호출한다.
+ */
+export function setSharedLayout(layoutFilePath: string): void {
+    sharedLayoutPath = resolve(layoutFilePath);
+    // 경로가 바뀌면 캐시 무효화
+    cache.delete(sharedLayoutPath);
+}
+
+/**
+ * 템플릿 디렉토리를 설정한다.
+ * @deprecated 각 플러그인/라우트에서 renderTemplate 의 dir 인자를 직접 전달하세요.
+ */
+export function setTemplateDir(dir: string): void {
+    templateDir = resolve(dir);
+}
+
+/**
+ * 변수 맵으로 문자열 내 `${key}` / `${key|default}` 를 치환한다.
+ */
+export function replaceVars(
+    template: string,
+    data: Record<string, unknown>,
+): string {
+    return template.replace(
+        VAR_PATTERN,
+        (_match, key: string, defaultVal?: string) => {
+            const val = data[key];
+            if (val !== undefined && val !== null && String(val) !== "") {
+                return String(val);
+            }
+            return defaultVal ?? "";
+        },
+    );
+}
+
+/**
+ * 템플릿 파일을 로드한다 (캐시 적용).
+ * @param name - 상대경로 (예: "password_reset")
+ * @param dir  - 템플릿 디렉토리
+ */
+function loadFile(name: string, dir: string): string | null {
+    const cacheKey = `${dir}|${name}`;
+    if (cache.has(cacheKey)) return cache.get(cacheKey)!;
+
+    const filePath = join(dir, `${name}.html`);
+    if (!existsSync(filePath)) {
+        logger.warn({ path: filePath }, "Email template not found");
+        return null;
+    }
+
+    const content = readFileSync(filePath, "utf-8");
+    cache.set(cacheKey, content);
+    return content;
+}
+
+/** 공유 레이아웃 HTML을 로드한다 (캐시 적용) */
+function loadSharedLayout(): string | null {
+    if (!sharedLayoutPath) return null;
+    if (cache.has(sharedLayoutPath)) return cache.get(sharedLayoutPath)!;
+
+    if (!existsSync(sharedLayoutPath)) {
+        logger.warn(
+            { path: sharedLayoutPath },
+            "Shared email layout not found",
+        );
+        return null;
+    }
+
+    const content = readFileSync(sharedLayoutPath, "utf-8");
+    cache.set(sharedLayoutPath, content);
+    return content;
+}
+
+/**
+ * 템플릿을 렌더링한다.
+ *
+ * 콘텐츠 HTML을 렌더링한 뒤 공유 레이아웃(plugins/smtp/templates/layout.html)으로 감싼다.
+ *
+ * @param name - 템플릿 상대경로 (확장자 제외, 예: "password_reset")
+ * @param data - 치환용 변수 맵
+ * @param dir  - 템플릿 디렉토리 절대경로 (미지정 시 setTemplateDir 값 사용)
+ * @returns 렌더링된 HTML 또는 null (템플릿 미존재)
+ */
+export function renderTemplate(
+    name: string,
+    data: Record<string, unknown>,
+    dir?: string,
+): string | null {
+    const effectiveDir = resolve(dir ?? templateDir);
+    const tpl = loadFile(name, effectiveDir);
+    if (!tpl) return null;
+
+    const rendered = replaceVars(tpl, data);
+
+    const layout = loadSharedLayout();
+    if (layout) {
+        return replaceVars(layout, { ...data, content: rendered });
+    }
+
+    return rendered;
+}
+
+/**
+ * 인라인 문자열에 변수를 치환한다 (파일 로딩 없이).
+ */
+export function renderString(
+    template: string,
+    data: Record<string, unknown>,
+): string {
+    return replaceVars(template, data);
+}
+
+/** 캐시를 초기화한다 (테스트/리로드용) */
+export function clearTemplateCache(): void {
+    cache.clear();
+}

package/src/system/entity-server/bootstrap.ts

@@ -0,0 +1,270 @@
+import { fileURLToPath } from "url";
+import { readdirSync, readFileSync, existsSync } from "fs";
+import path from "path";
+import { logger } from "../config/env.ts";
+import { postEntityAdmin } from "./client.ts";
+
+type EnsureEntityResult = {
+    ok?: boolean;
+    action?: string;
+    changes?: unknown;
+    schema?: unknown;
+    message?: string;
+};
+
+type BatchEnsureItem = {
+    name: string;
+    source: string;
+    config: Record<string, unknown>;
+};
+
+type BatchEnsureResult = {
+    name: string;
+    action?: string;
+    schema?: unknown;
+    error?: string;
+};
+
+/** import.meta.url 또는 __dirname 등 다양한 형태의 경로를 플러그인 디렉토리 절대경로로 정규화한다. */
+function normalizePluginDirPath(pluginDirOrUrl: string): string {
+    let p = pluginDirOrUrl;
+    if (p.startsWith("file://")) {
+        p = fileURLToPath(p);
+    }
+    // 파일 경로인 경우(index.ts 등) 디렉토리로 변환
+    if (p.endsWith(".ts") || p.endsWith(".js") || p.endsWith(".mjs")) {
+        p = path.dirname(p);
+    }
+    return path.resolve(p);
+}
+
+/** 이미 처리된 플러그인 디렉토리 캐시 (중복 HTTP 요청 방지) */
+const _ensuredDirs = new Set<string>();
+
+/** 플러그인 디렉토리 경로를 엔티티 출처 헤더용 상대 경로로 정규화한다. */
+function resolveEntitySource(pluginDir: string): string {
+    const normalized = pluginDir.replace(/\\/g, "/");
+    const match = normalized.match(/\/(?:src|dist)\/app\/(.+)$/);
+    if (match?.[1]) {
+        return match[1].replace(/^\/+|\/+$/g, "");
+    }
+    return path.basename(pluginDir);
+}
+
+/** 엔티티 서버 admin POST 요청을 공통 형식으로 전송한다. */
+async function postAdmin<T>(
+    urlPath: string,
+    body = "",
+    entitySource?: string,
+): Promise<T> {
+    return postEntityAdmin<T>(
+        urlPath,
+        body,
+        entitySource ? { "X-Entity-Source": entitySource } : {},
+    );
+}
+
+/** 지정한 엔티티의 schema sync를 실행하고 결과를 반환한다. */
+async function syncEntitySchema(entityName: string): Promise<unknown> {
+    const result = await postAdmin<EnsureEntityResult>(
+        `/${entityName}/sync-schema`,
+    );
+    return result.schema;
+}
+
+/** schema sync 결과에 실제 컬럼 변경이 포함됐는지 판별한다. */
+function hasSchemaDiff(schema: unknown): boolean {
+    if (!schema || typeof schema !== "object") return false;
+    const typedSchema = schema as {
+        added_columns?: unknown[];
+        dropped_columns?: unknown[];
+    };
+    return (
+        (typedSchema.added_columns?.length ?? 0) > 0 ||
+        (typedSchema.dropped_columns?.length ?? 0) > 0
+    );
+}
+
+/** 단일 엔티티 생성/동기화 결과에 따라 후속 schema sync와 로그를 처리한다. */
+async function ensureEntity(
+    entityName: string,
+    config: Record<string, unknown>,
+    entitySource?: string,
+): Promise<void> {
+    const body = JSON.stringify(config);
+    const result = await postAdmin<EnsureEntityResult>(
+        `/${entityName}/create`,
+        body,
+        entitySource,
+    );
+
+    if (result.action === "already_exists") {
+        const schema = await syncEntitySchema(entityName);
+        if (hasSchemaDiff(schema)) {
+            logger.info(
+                { entityName, schema },
+                "ensurePluginEntities: schema updated",
+            );
+        }
+        return;
+    }
+
+    if (result.action === "synced") {
+        if (hasSchemaDiff(result.schema)) {
+            logger.info(
+                { entityName, changes: result.changes, schema: result.schema },
+                "ensurePluginEntities: schema synced (new fields/indexes applied)",
+            );
+        }
+        return;
+    }
+
+    if (result.action === "created") {
+        logger.info(
+            { entityName },
+            "ensurePluginEntities: entity created (tables initialized)",
+        );
+        return;
+    }
+
+    const schema = await syncEntitySchema(entityName);
+    logger.info(
+        { entityName, schema },
+        "ensurePluginEntities: entity saved, sync-schema applied",
+    );
+}
+
+/**
+ * 플러그인 디렉토리의 entities/*.json 을 읽어 엔티티 서버에 등록한다.
+ * import.meta.url, __dirname, 절대경로 모두 허용한다.
+ * 이미 batchEnsureAllPluginEntities 로 처리된 디렉토리는 즉시 반환한다.
+ *
+ * @param pluginDirOrUrl 플러그인 디렉토리 또는 파일 URL (import.meta.url 등)
+ */
+export async function ensurePluginEntities(
+    pluginDirOrUrl: string,
+): Promise<void> {
+    const pluginDir = normalizePluginDirPath(pluginDirOrUrl);
+
+    if (_ensuredDirs.has(pluginDir)) return;
+    _ensuredDirs.add(pluginDir);
+
+    const entitiesDir = path.join(pluginDir, "entities");
+    if (!existsSync(entitiesDir)) return;
+
+    const files = readdirSync(entitiesDir).filter((file) =>
+        file.endsWith(".json"),
+    );
+    if (files.length === 0) return;
+
+    const entitySource = resolveEntitySource(pluginDir);
+    await Promise.allSettled(
+        files.map(async (file) => {
+            const entityName = path.basename(file, ".json");
+            try {
+                const raw = readFileSync(path.join(entitiesDir, file), "utf-8");
+                const config = JSON.parse(raw) as Record<string, unknown>;
+                await ensureEntity(entityName, config, entitySource);
+            } catch (err) {
+                logger.warn(
+                    { err, entityName, pluginDir },
+                    "ensurePluginEntities: failed to ensure entity",
+                );
+            }
+        }),
+    );
+}
+
+/**
+ * 여러 플러그인의 모든 엔티티를 단일 배치 요청으로 한 번에 등록/동기화한다.
+ * 처리된 디렉토리는 캐시에 추가되어 이후 ensurePluginEntities 호출이 no-op이 된다.
+ *
+ * @param pluginDirs 플러그인 디렉토리 경로 배열 (절대경로 또는 URL)
+ */
+export async function batchEnsureAllPluginEntities(
+    pluginDirs: string[],
+): Promise<void> {
+    const items: BatchEnsureItem[] = [];
+    const processedDirs: string[] = [];
+
+    for (const pluginDirOrUrl of pluginDirs) {
+        const pluginDir = normalizePluginDirPath(pluginDirOrUrl);
+
+        if (_ensuredDirs.has(pluginDir)) continue;
+
+        const entitiesDir = path.join(pluginDir, "entities");
+        if (!existsSync(entitiesDir)) {
+            _ensuredDirs.add(pluginDir);
+            continue;
+        }
+
+        const files = readdirSync(entitiesDir).filter((f) =>
+            f.endsWith(".json"),
+        );
+        if (files.length === 0) {
+            _ensuredDirs.add(pluginDir);
+            continue;
+        }
+
+        const source = resolveEntitySource(pluginDir);
+        for (const file of files) {
+            const entityName = path.basename(file, ".json");
+            try {
+                const raw = readFileSync(path.join(entitiesDir, file), "utf-8");
+                const config = JSON.parse(raw) as Record<string, unknown>;
+                items.push({ name: entityName, source, config });
+            } catch (err) {
+                logger.warn(
+                    { err, entityName, pluginDir },
+                    "batchEnsureAllPluginEntities: failed to read entity file",
+                );
+            }
+        }
+        processedDirs.push(pluginDir);
+    }
+
+    if (items.length === 0) {
+        for (const d of processedDirs) _ensuredDirs.add(d);
+        return;
+    }
+
+    try {
+        const response = await postEntityAdmin<{
+            ok: boolean;
+            results: BatchEnsureResult[];
+        }>("/entities/batch-ensure", JSON.stringify(items));
+
+        // 성공 시 모든 디렉토리를 캐시에 등록
+        for (const d of processedDirs) _ensuredDirs.add(d);
+
+        for (const result of response.results ?? []) {
+            if (result.error) {
+                logger.warn(
+                    { entityName: result.name, error: result.error },
+                    "batchEnsureAllPluginEntities: entity error",
+                );
+                continue;
+            }
+            if (result.action === "created") {
+                logger.info(
+                    { entityName: result.name },
+                    "ensurePluginEntities: entity created (tables initialized)",
+                );
+            } else if (
+                result.action === "synced" &&
+                hasSchemaDiff(result.schema)
+            ) {
+                logger.info(
+                    { entityName: result.name, schema: result.schema },
+                    "ensurePluginEntities: schema synced (new fields/indexes applied)",
+                );
+            }
+        }
+    } catch (err) {
+        // 배치 실패 시 캐시에 추가하지 않아 개별 ensure로 폴백
+        logger.warn(
+            { err },
+            "batchEnsureAllPluginEntities: batch request failed, falling back to individual ensures",
+        );
+    }
+}

package/src/system/entity-server/client.ts

@@ -0,0 +1,64 @@
+import { createHmac } from "node:crypto";
+import { env } from "../config/env.ts";
+
+/** Entity Server admin API 절대 URL을 구성한다. */
+function buildAdminUrl(urlPath: string): string {
+    return `${env.ENTITY_SERVER_URL}/v1/admin${urlPath}`;
+}
+
+/** Entity Server admin API 서명 기준 경로를 구성한다. */
+function buildAdminSignPath(urlPath: string): string {
+    return `/v1/admin${urlPath}`;
+}
+
+/** admin API HMAC 서명 헤더를 생성한다. */
+export function buildAdminRequestHeaders(
+    method: string,
+    urlPath: string,
+    body: string,
+    extraHeaders: Record<string, string> = {},
+): Record<string, string> {
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const nonce = crypto.randomUUID();
+    const payload = Buffer.concat([
+        Buffer.from(
+            `${method}|${buildAdminSignPath(urlPath)}|${timestamp}|${nonce}|`,
+            "utf-8",
+        ),
+        Buffer.from(body, "utf-8"),
+    ]);
+    const signature = createHmac("sha256", env.ENTITY_HMAC_SECRET)
+        .update(payload)
+        .digest("hex");
+
+    return {
+        "Content-Type": "application/json",
+        "X-API-Key": env.ENTITY_API_KEY,
+        "X-Timestamp": timestamp,
+        "X-Nonce": nonce,
+        "X-Signature": signature,
+        ...extraHeaders,
+    };
+}
+
+/** Entity Server admin POST 요청을 전송하고 JSON 응답을 반환한다. */
+export async function postEntityAdmin<T>(
+    urlPath: string,
+    body = "",
+    extraHeaders: Record<string, string> = {},
+): Promise<T> {
+    const response = await fetch(buildAdminUrl(urlPath), {
+        method: "POST",
+        headers: buildAdminRequestHeaders("POST", urlPath, body, extraHeaders),
+        body: body || undefined,
+    });
+
+    if (!response.ok) {
+        const responseText = await response.text().catch(() => "");
+        throw new Error(
+            `admin request failed '${urlPath}': ${response.status} ${responseText}`,
+        );
+    }
+
+    return (await response.json().catch(() => ({}))) as T;
+}

package/src/system/hooks/loader.ts

@@ -0,0 +1,32 @@
+/**
+ * 훅 로더 — app/hooks/index.ts 를 동적 로드하여 훅 레지스트리에 등록
+ */
+
+import path from "path";
+import { setHookRegistry } from "./runner.ts";
+import { logger } from "../config/env.ts";
+import { resolveAppRoot } from "../utils/app-path.ts";
+import { resolveModulePath } from "../config/module-path.ts";
+
+/** app/hooks/index에서 엔티티 훅을 동적 로드한다 */
+export async function loadHooks(): Promise<number> {
+    const target = resolveModulePath(
+        path.join(resolveAppRoot(import.meta.url), "hooks"),
+        "index",
+    );
+    if (!target) {
+        return 0;
+    }
+    try {
+        const mod = await import(target);
+        if (mod.hookRegistry && typeof mod.hookRegistry === "object") {
+            setHookRegistry(mod.hookRegistry);
+            const count = Object.keys(mod.hookRegistry).length;
+            return count;
+        }
+    } catch (err) {
+        logger.error({ err }, "Failed to load hook registry");
+    }
+
+    return 0;
+}