create-entity-app-server 0.0.3 → 0.0.4

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

@@ -1,147 +0,0 @@
-/**
- * 이메일 템플릿 엔진
- *
- * 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

@@ -1,270 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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

@@ -1,32 +0,0 @@
-/**
- * 훅 로더 — 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;
-}

package/src/system/hooks/runner.ts

@@ -1,159 +0,0 @@
-/**
- * 훅 실행기 — 등록된 엔티티별 훅을 실행합니다.
- *
- * 에러 처리 정책:
- *   before* — 예외 시 throw → error-handler.ts 가 400/500 반환 (차단)
- *   after*  — 예외 시 로그만 남기고 원본 result 반환 (무시)
- */
-
-import type {
-    EntityHook,
-    UserInfo,
-    SubmitContext,
-    DeleteContext,
-} from "./types.ts";
-import { logger } from "../config/env.ts";
-
-/** 훅 레지스트리 — loader.ts 가 app/hooks/index.ts를 로드하여 채움 */
-let hookRegistry: Record<string, EntityHook> = {};
-
-/** 훅 레지스트리를 설정한다 */
-export function setHookRegistry(registry: Record<string, EntityHook>): void {
-    hookRegistry = registry;
-}
-
-/** 현재 훅 레지스트리를 반환한다 */
-export function getHookRegistry(): Record<string, EntityHook> {
-    return hookRegistry;
-}
-
-/** 엔티티에 등록된 훅이 있는지 확인한다 */
-export function hasHook(entity: string): boolean {
-    return entity in hookRegistry;
-}
-
-/** 엔티티에 특정 이름의 훅이 등록되어 있는지 확인한다 */
-export function hasSpecificHook(
-    entity: string,
-    hookName: keyof EntityHook,
-): boolean {
-    const hook = hookRegistry[entity];
-    return hook != null && typeof hook[hookName] === "function";
-}
-
-// --- before 훅: 실패 시 차단 (throw) ---
-
-/** get 전 훅을 실행하고 허용 여부를 반환한다 */
-export async function runBeforeGet(
-    entity: string,
-    seq: number,
-    user: UserInfo,
-): Promise<boolean> {
-    const hook = hookRegistry[entity];
-    if (!hook?.beforeGet) return true;
-    return await hook.beforeGet(entity, seq, user);
-}
-
-/**
- * submit 전 훅을 실행한다.
- * ctx.new를 변경한 반환값이 실제 submit 데이터가 된다.
- */
-export async function runBeforeSubmit(
-    entity: string,
-    ctx: SubmitContext,
-    user: UserInfo,
-): Promise<any> {
-    const hook = hookRegistry[entity];
-    if (!hook?.beforeSubmit) return ctx.new;
-    return await hook.beforeSubmit(entity, ctx, user);
-}
-
-/** delete 전 훅을 실행하고 허용 여부를 반환한다 */
-export async function runBeforeDelete(
-    entity: string,
-    ctx: DeleteContext,
-    user: UserInfo,
-): Promise<boolean> {
-    const hook = hookRegistry[entity];
-    if (!hook?.beforeDelete) return true;
-    return await hook.beforeDelete(entity, ctx, user);
-}
-
-/** list 전 훅을 실행하고 변환된 파라미터를 반환한다 */
-export async function runBeforeList(
-    entity: string,
-    params: any,
-    user: UserInfo,
-): Promise<any> {
-    const hook = hookRegistry[entity];
-    if (!hook?.beforeList) return params;
-    return await hook.beforeList(entity, params, user);
-}
-
-// --- after 훅: 실패 시 로그만 남기고 무시 ---
-
-/** get 후 훅을 실행한다. 반환값이 클라이언트 응답이 된다 (실패 시 원본 반환) */
-export async function runAfterGet(
-    entity: string,
-    data: any,
-    user: UserInfo,
-): Promise<any> {
-    const hook = hookRegistry[entity];
-    if (!hook?.afterGet) return data;
-    try {
-        return await hook.afterGet(entity, data, user);
-    } catch (err) {
-        logger.error({ entity, err }, "afterGet hook failed — ignored");
-        return data;
-    }
-}
-
-/**
- * submit 후 훅을 실행한다.
- * ctx.old/ctx.new로 변경 전후 비교가 가능하다.
- */
-export async function runAfterSubmit(
-    entity: string,
-    ctx: SubmitContext,
-    user: UserInfo,
-): Promise<any> {
-    const hook = hookRegistry[entity];
-    if (!hook?.afterSubmit) return ctx.new;
-    try {
-        return await hook.afterSubmit(entity, ctx, user);
-    } catch (err) {
-        logger.error({ entity, err }, "afterSubmit hook failed — ignored");
-        return ctx.new;
-    }
-}
-
-/** delete 후 훅을 실행한다 (실패 시 무시) */
-export async function runAfterDelete(
-    entity: string,
-    ctx: DeleteContext,
-    user: UserInfo,
-): Promise<void> {
-    const hook = hookRegistry[entity];
-    if (!hook?.afterDelete) return;
-    try {
-        await hook.afterDelete(entity, ctx, user);
-    } catch (err) {
-        logger.error({ entity, err }, "afterDelete hook failed — ignored");
-    }
-}
-
-/** list 후 훅을 실행한다 (실패 시 무시) */
-export async function runAfterList(
-    entity: string,
-    result: any,
-    user: UserInfo,
-): Promise<any> {
-    const hook = hookRegistry[entity];
-    if (!hook?.afterList) return result;
-    try {
-        return await hook.afterList(entity, result, user);
-    } catch (err) {
-        logger.error({ entity, err }, "afterList hook failed — ignored");
-        return result;
-    }
-}