create-entity-app-server 0.0.3

package/scripts/_gen-table-type.ts

@@ -0,0 +1,605 @@
+// @ts-nocheck
+/**
+ * _gen-table-type.ts — 엔티티 메타 → Kysely 테이블 타입 생성기
+ *
+ * gen-table-type.sh 에서 호출됩니다.
+ * 엔티티서버 /v1/entity/:entity/meta API를 호출하여 필드 정보를 조회하고
+ * src/app/models/{entity}.ts 파일을 생성합니다.
+ *
+ * 엔티티서버의 DB 스키마:
+ *   - 공통 컬럼: seq (PK, auto_increment), created_time, updated_time, deleted_time, license
+ *   - 인덱스 필드: index: true → 별도 인덱스 테이블 컬럼
+ *   - 데이터 필드: data JSON blob에 저장
+ *
+ * 생성되는 타입 구조:
+ *   - {Entity}Table        — Kysely 테이블 정의 (공통 컬럼 + 인덱스 컬럼)
+ *   - {Entity}Data         — data JSON blob 필드 타입
+ *   - {Entity}Row          — 전체 행 타입 (Table + Data 통합)
+ */
+
+import {
+    writeFileSync,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    readdirSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+import { createHmac, randomUUID } from "node:crypto";
+
+// ── HMAC 서명 헤더 생성 ──────────────────────────────────────────────────────
+
+/**
+ * 엔티티서버 HMAC-SHA256 서명 헤더를 생성합니다.
+ * 서명 대상: `METHOD|PATH|TIMESTAMP|NONCE|BODY`
+ * PATH는 쿼리 파라미터를 제외한 경로만 사용합니다 (Fiber c.Path() 일치).
+ */
+function buildHmacHeaders(
+    method: string,
+    fullPath: string,
+    body: string,
+    apiKey: string,
+    hmacSecret: string,
+): Record<string, string> {
+    const signPath = fullPath.split("?")[0]; // 쿼리 파라미터 제거
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const nonce = randomUUID();
+    const payload = `${method}|${signPath}|${timestamp}|${nonce}|${body}`;
+    const signature = createHmac("sha256", hmacSecret)
+        .update(payload)
+        .digest("hex");
+
+    return {
+        "X-API-Key": apiKey,
+        "X-Timestamp": timestamp,
+        "X-Nonce": nonce,
+        "X-Signature": signature,
+    };
+}
+
+// ── 인자 파싱 ────────────────────────────────────────────────────────────────
+
+interface Args {
+    entities: string[];
+    serverUrl: string;
+    apiKey: string;
+    hmacSecret: string;
+    outDir: string;
+    dryRun: boolean;
+    force: boolean;
+}
+
+function parseArgs(): Args {
+    const args: Args = {
+        entities: [],
+        serverUrl: "",
+        apiKey: "",
+        hmacSecret: "",
+        outDir: "",
+        dryRun: false,
+        force: false,
+    };
+
+    for (const arg of process.argv.slice(2)) {
+        if (arg.startsWith("--entities=")) {
+            args.entities = arg
+                .slice("--entities=".length)
+                .split(",")
+                .filter(Boolean);
+        } else if (arg.startsWith("--server-url=")) {
+            args.serverUrl = arg.slice("--server-url=".length);
+        } else if (arg.startsWith("--api-key=")) {
+            args.apiKey = arg.slice("--api-key=".length);
+        } else if (arg.startsWith("--hmac-secret=")) {
+            args.hmacSecret = arg.slice("--hmac-secret=".length);
+        } else if (arg.startsWith("--out-dir=")) {
+            args.outDir = arg.slice("--out-dir=".length);
+        } else if (arg === "--dry-run") {
+            args.dryRun = true;
+        } else if (arg === "--force") {
+            args.force = true;
+        }
+    }
+
+    if (!args.entities.length) throw new Error("--entities required");
+    if (!args.serverUrl) throw new Error("--server-url required");
+    if (!args.apiKey) throw new Error("--api-key required");
+    if (!args.hmacSecret) throw new Error("--hmac-secret required");
+    if (!args.outDir) throw new Error("--out-dir required");
+
+    return args;
+}
+
+// ── 엔티티 메타 조회 ────────────────────────────────────────────────────────
+
+interface FieldDef {
+    type?: string | string[];
+    comment?: string;
+    required?: boolean;
+    nullable?: boolean;
+    default?: unknown;
+    no_store?: boolean;
+    fields?: Record<string, FieldDef>;
+}
+
+interface IndexFieldDef extends FieldDef {
+    index?: boolean;
+    unique?: boolean;
+    hash?: boolean;
+    index_only?: boolean;
+}
+
+interface EntityMeta {
+    name: string;
+    description?: string;
+    index?: string[];
+    types?: Record<string, unknown>;
+    fields?: Record<string, FieldDef>;
+    required?: string[];
+    nullable?: string[];
+    unique?: (string | string[])[];
+    comments?: Record<string, string>;
+    // 파싱 후 재구성용
+    _indexDetails?: Record<string, IndexFieldDef>;
+}
+
+async function fetchEntityMeta(
+    serverUrl: string,
+    apiKey: string,
+    hmacSecret: string,
+    entity: string,
+): Promise<EntityMeta> {
+    const path = `/v1/entity/${entity}/meta`;
+    const url = `${serverUrl}${path}`;
+    const headers = buildHmacHeaders("GET", path, "", apiKey, hmacSecret);
+    const resp = await fetch(url, { headers });
+
+    if (!resp.ok) {
+        throw new Error(
+            `${entity}: meta API failed: ${resp.status} ${resp.statusText}`,
+        );
+    }
+
+    const json = (await resp.json()) as {
+        ok: boolean;
+        data?: EntityMeta;
+        error?: string;
+    };
+    if (!json.ok || !json.data) {
+        throw new Error(
+            `${entity}: meta API error: ${json.error ?? "unknown"}`,
+        );
+    }
+
+    return json.data;
+}
+
+// ── 엔티티 원본 JSON에서 필드 상세 조회 ──────────────────────────────────────
+// meta API는 IndexDetails를 `-` 태그로 숨기므로, 원본 설정 파일 API를 추가 호출
+
+async function fetchEntityConfig(
+    serverUrl: string,
+    apiKey: string,
+    hmacSecret: string,
+    entity: string,
+): Promise<Record<string, any>> {
+    // admin config 엔드포인트에서 원본 JSON 조회
+    const path = `/v1/admin/${entity}/config`;
+    const url = `${serverUrl}${path}`;
+    const headers = buildHmacHeaders("GET", path, "", apiKey, hmacSecret);
+    const resp = await fetch(url, { headers });
+
+    if (!resp.ok) {
+        // admin API가 없으면 meta만 사용
+        return {};
+    }
+
+    const json = (await resp.json()) as {
+        ok: boolean;
+        data?: Record<string, any>;
+    };
+    return json.data ?? {};
+}
+
+// ── 타입 매핑 ────────────────────────────────────────────────────────────────
+
+/** 엔티티 필드 타입 → TypeScript 타입 문자열 변환 */
+function mapFieldType(fieldType: unknown, fieldName: string): string {
+    if (fieldType === undefined || fieldType === null) {
+        return "string"; // 기본: 범용 VARCHAR → string
+    }
+
+    // 배열 = enum
+    if (Array.isArray(fieldType)) {
+        if (fieldType.length === 0) return "string";
+        return fieldType.map((v) => JSON.stringify(String(v))).join(" | ");
+    }
+
+    const t = String(fieldType).toLowerCase().trim();
+
+    // 정확한 매핑
+    switch (t) {
+        case "string":
+        case "email":
+        case "phone":
+            return "string";
+        case "bool":
+            return "boolean";
+        case "uint":
+        case "int":
+        case "integer":
+        case "float":
+        case "number":
+            return "number";
+        case "file":
+            return "string"; // 파일 참조 seq (문자열)
+        case "file[]":
+            return "string[]"; // 파일 참조 seq 배열
+        default:
+            // varchar(N) → string
+            if (t.startsWith("varchar")) return "string";
+            // text → string
+            if (t === "text" || t === "longtext") return "string";
+            return "string";
+    }
+}
+
+/** 인덱스 필드 타입에서 Kysely 컬럼 타입 결정 */
+function mapIndexColumnType(
+    fieldType: unknown,
+    fieldName: string,
+    opts: { nullable: boolean; hasDefault: boolean; defaultVal?: unknown },
+): string {
+    const tsType = mapFieldType(fieldType, fieldName);
+
+    if (opts.nullable) {
+        return `${tsType} | null`;
+    }
+    return tsType;
+}
+
+// ── 코드 생성 ────────────────────────────────────────────────────────────────
+
+/** snake_case → PascalCase */
+function toPascalCase(s: string): string {
+    return s
+        .split(/[-_]/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join("");
+}
+
+/** 필드 코멘트 → JSDoc 한 줄 */
+function commentLine(comment: string | undefined, indent: string): string {
+    if (!comment) return "";
+    return `${indent}/** ${comment} */\n`;
+}
+
+interface GeneratedType {
+    fileName: string;
+    tableName: string;
+    interfaceName: string;
+    content: string;
+}
+
+function generateTableType(
+    meta: EntityMeta,
+    rawConfig: Record<string, any>,
+): GeneratedType {
+    const entityName = meta.name;
+    const pascal = toPascalCase(entityName);
+    const tableName = `${pascal}Table`;
+    const dataName = `${pascal}Data`;
+    const rowName = `${pascal}Row`;
+
+    // 원본 config의 fields에서 index 필드 상세를 추출
+    const rawFields: Record<string, any> = rawConfig.fields ?? {};
+
+    // index 필드 수집 (meta.index 배열 + types 매핑)
+    const indexFields: string[] = meta.index ?? [];
+    const types: Record<string, unknown> = meta.types ?? {};
+    const required = new Set(meta.required ?? []);
+    const nullable = new Set(meta.nullable ?? []);
+    const comments: Record<string, string> = (meta.comments ?? {}) as Record<
+        string,
+        string
+    >;
+
+    // data 필드 수집 (meta.fields)
+    const dataFields: Record<string, FieldDef> = meta.fields ?? {};
+
+    const lines: string[] = [];
+
+    // 헤더
+    lines.push("/**");
+    lines.push(` * ${tableName} — ${entityName} 엔티티 테이블 타입 정의`);
+    if (meta.description) {
+        lines.push(` *`);
+        lines.push(` * ${meta.description}`);
+    }
+    lines.push(` *`);
+    lines.push(` * @generated gen-table-type.sh 에 의해 자동 생성됨`);
+    lines.push(` * @see https://kysely.dev/docs/getting-started#types`);
+    lines.push(` */`);
+    lines.push(``);
+    lines.push(`import type { Generated, ColumnType } from "kysely";`);
+    lines.push(``);
+
+    // ── Table 인터페이스 (공통 컬럼 + 인덱스 컬럼) ──
+    lines.push(`/** ${entityName} 인덱스 테이블 — 공통 컬럼 + 인덱스 필드 */`);
+    lines.push(`export interface ${tableName} {`);
+
+    // 공통 컬럼
+    lines.push(`    /** 시퀀스 (PK, auto_increment) */`);
+    lines.push(`    seq: Generated<number>;`);
+
+    // 인덱스 필드
+    for (const field of indexFields) {
+        const rawField = rawFields[field] ?? {};
+        const fieldType = types[field] ?? rawField.type;
+        const comment = comments[field] ?? rawField.comment;
+        const isNullable =
+            nullable.has(field) ||
+            (rawField.nullable !== false &&
+                !required.has(field) &&
+                !rawField.required);
+        const hasDefault = rawField.default !== undefined;
+        const isHash = rawField.hash === true;
+        const isUnique = rawField.unique === true;
+
+        const tsType = mapIndexColumnType(fieldType, field, {
+            nullable: isNullable,
+            hasDefault,
+            defaultVal: rawField.default,
+        });
+
+        // JSDoc
+        const docParts: string[] = [];
+        if (comment) docParts.push(comment);
+        if (isHash) docParts.push("(hash 저장)");
+        if (isUnique) docParts.push("(unique)");
+        if (hasDefault)
+            docParts.push(`기본값: ${JSON.stringify(rawField.default)}`);
+
+        if (docParts.length > 0) {
+            lines.push(`    /** ${docParts.join(" — ")} */`);
+        }
+
+        // Generated 래핑: default가 있거나 nullable이면 INSERT 시 생략 가능
+        if (hasDefault || isNullable) {
+            lines.push(`    ${field}: Generated<${tsType}>;`);
+        } else {
+            lines.push(`    ${field}: ${tsType};`);
+        }
+    }
+
+    // data JSON blob 컬럼
+    lines.push(`    /** 데이터 JSON blob */`);
+    lines.push(`    data: string;`);
+
+    // 공통 타임스탬프 컬럼
+    lines.push(`    /** 생성 시각 */`);
+    lines.push(`    created_time: Generated<string>;`);
+    lines.push(`    /** 수정 시각 */`);
+    lines.push(`    updated_time: Generated<string>;`);
+    lines.push(`    /** 삭제 시각 (soft delete) */`);
+    lines.push(`    deleted_time: Generated<string | null>;`);
+    lines.push(`    /** 라이선스 */`);
+    lines.push(`    license: Generated<string>;`);
+
+    lines.push(`}`);
+    lines.push(``);
+
+    // ── Data 인터페이스 (data blob 내 필드) ──
+    const dataFieldNames = Object.keys(dataFields).filter(
+        (f) => !dataFields[f].no_store,
+    );
+
+    if (dataFieldNames.length > 0) {
+        lines.push(`/** ${entityName} data JSON blob 필드 타입 */`);
+        lines.push(`export interface ${dataName} {`);
+
+        for (const field of dataFieldNames) {
+            const def = dataFields[field];
+            const tsType = mapFieldType(def.type, field);
+            const isOptional = !def.required;
+
+            if (def.comment) {
+                lines.push(`    /** ${def.comment} */`);
+            }
+            lines.push(`    ${field}${isOptional ? "?" : ""}: ${tsType};`);
+        }
+
+        lines.push(`}`);
+        lines.push(``);
+    }
+
+    // ── Row 타입 (통합 뷰) ──
+    lines.push(`/** ${entityName} 전체 행 타입 — API 응답에서 사용 */`);
+    lines.push(`export interface ${rowName} {`);
+    lines.push(`    seq: number;`);
+
+    // 인덱스 필드 (간결하게)
+    for (const field of indexFields) {
+        const rawField = rawFields[field] ?? {};
+        const fieldType = types[field] ?? rawField.type;
+        const tsType = mapFieldType(fieldType, field);
+        const isNullable =
+            nullable.has(field) ||
+            (rawField.nullable !== false &&
+                !required.has(field) &&
+                !rawField.required);
+        lines.push(`    ${field}${isNullable ? "?" : ""}: ${tsType};`);
+    }
+
+    // 데이터 필드 (모두 optional)
+    for (const field of dataFieldNames) {
+        const def = dataFields[field];
+        const tsType = mapFieldType(def.type, field);
+        lines.push(`    ${field}?: ${tsType};`);
+    }
+
+    lines.push(`    created_time: string;`);
+    lines.push(`    updated_time: string;`);
+    lines.push(`    deleted_time?: string | null;`);
+    lines.push(`}`);
+    lines.push(``);
+
+    return {
+        fileName: `${entityName}.ts`,
+        tableName,
+        interfaceName: tableName,
+        content: lines.join("\n"),
+    };
+}
+
+// ── models/index.ts 자동 업데이트 ────────────────────────────────────────────
+
+/**
+ * outDir(models/) 아래의 모든 .ts 파일을 스캔하여
+ * models/index.ts 의 import / Database 인터페이스를 재생성한다.
+ */
+function updateDatabaseIndex(outDir: string): void {
+    const indexPath = join(outDir, "index.ts");
+
+    const files = readdirSync(outDir)
+        .filter((f) => f.endsWith(".ts") && f !== "index.ts")
+        .sort();
+
+    const entries = files.map((file) => {
+        const entityName = file.replace(/\.ts$/, "");
+        const pascal = toPascalCase(entityName);
+        return { entityName, tableName: `${pascal}Table` };
+    });
+
+    const lines: string[] = [];
+    lines.push(`/**`);
+    lines.push(
+        ` * Database 인터페이스 — Kysely 타입 안전 쿼리를 위한 테이블 매핑`,
+    );
+    lines.push(` *`);
+    lines.push(
+        ` * 각 테이블 타입을 별도 파일로 정의하고, 여기서 Database 인터페이스에 매핑합니다.`,
+    );
+    lines.push(
+        ` * req.server.db!.selectFrom("account") 에서 자동완성 + 타입 체크가 적용됩니다.`,
+    );
+    lines.push(` *`);
+    lines.push(
+        ` * 등록하지 않은 테이블은 sql\`\` 태그드 리터럴(raw SQL)로 접근할 수 있습니다.`,
+    );
+    lines.push(` *`);
+    lines.push(` *   import { sql } from "@gateway/api";`);
+    lines.push(
+        ` *   const result = await sql<{ count: number }>\`SELECT COUNT(*) as count FROM some_table\`.execute(db);`,
+    );
+    lines.push(` *`);
+    lines.push(` * @generated gen-table-type.sh 에 의해 자동 관리됨`);
+    lines.push(` * @see https://kysely.dev/docs/getting-started#types`);
+    lines.push(` */`);
+    lines.push(``);
+    lines.push(`export type { Generated, ColumnType } from "kysely";`);
+
+    for (const { entityName, tableName } of entries) {
+        lines.push(`export type { ${tableName} } from "./${entityName}.ts";`);
+    }
+
+    lines.push(``);
+
+    for (const { entityName, tableName } of entries) {
+        lines.push(`import type { ${tableName} } from "./${entityName}.ts";`);
+    }
+
+    lines.push(``);
+    lines.push(`export interface Database {`);
+    for (const { entityName, tableName } of entries) {
+        lines.push(`    ${entityName}: ${tableName};`);
+    }
+    lines.push(`    [key: string]: any; // 미등록 테이블 raw SQL 접근 허용`);
+    lines.push(`}`);
+    lines.push(``);
+
+    writeFileSync(indexPath, lines.join("\n"), "utf-8");
+    console.log(`  ✓ models/index.ts 업데이트 (${entries.length}개 테이블)`);
+}
+
+// ── 메인 ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+    const args = parseArgs();
+
+    if (!existsSync(args.outDir)) {
+        mkdirSync(args.outDir, { recursive: true });
+    }
+
+    console.log("");
+    console.log(`  엔티티 → 테이블 타입 생성  |  서버: ${args.serverUrl}`);
+    console.log("");
+
+    let success = 0;
+    let skipped = 0;
+    let failed = 0;
+
+    for (const entity of args.entities) {
+        const outPath = join(args.outDir, `${entity}.ts`);
+
+        // 기존 파일 확인
+        if (!args.force && existsSync(outPath)) {
+            console.log(
+                `  ⊘ ${entity} — 파일이 이미 존재합니다 (--force로 덮어쓰기)`,
+            );
+            skipped++;
+            continue;
+        }
+
+        try {
+            // 1. 메타 + 원본 config 조회
+            const [meta, rawConfig] = await Promise.all([
+                fetchEntityMeta(
+                    args.serverUrl,
+                    args.apiKey,
+                    args.hmacSecret,
+                    entity,
+                ),
+                fetchEntityConfig(
+                    args.serverUrl,
+                    args.apiKey,
+                    args.hmacSecret,
+                    entity,
+                ),
+            ]);
+
+            // 2. 타입 생성
+            const result = generateTableType(meta, rawConfig);
+
+            if (args.dryRun) {
+                console.log(`  ── ${entity} (dry-run) ──`);
+                console.log(result.content);
+                console.log(`  ── /${entity} ──`);
+            } else {
+                writeFileSync(outPath, result.content, "utf-8");
+                console.log(`  ✓ ${entity} → ${basename(outPath)}`);
+            }
+            success++;
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`  ✗ ${entity} — ${msg}`);
+            failed++;
+        }
+    }
+
+    console.log("");
+    console.log(`  완료: 성공 ${success}, 건너뜀 ${skipped}, 실패 ${failed}`);
+    console.log("");
+
+    // models/index.ts 자동 재생성 (dry-run 제외, 성공/건너뜀이 1개 이상일 때)
+    if (!args.dryRun && success + skipped > 0) {
+        updateDatabaseIndex(args.outDir);
+    }
+
+    if (failed > 0) process.exit(1);
+}
+
+main().catch((err) => {
+    console.error("❌ 치명적 오류:", err);
+    process.exit(1);
+});