gencow 0.1.112 → 0.1.114

package/bin/gencow.mjs

@@ -29,15 +29,37 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const CREDS_PATH = resolve(homedir(), ".gencow", "credentials.json");
 
+// ─── Domain Helpers (Dev/Prod 환경 분리) ─────────────────
+// platformUrl에서 기본 도메인을 추출하여 동적 URL 생성.
+// DEV: https://gencow.dev → gencow.dev
+// PROD: https://gencow.app → gencow.app
+
+function getBaseDomain(platformUrl) {
+    try {
+        return new URL(platformUrl).hostname;
+    } catch {
+        return "gencow.app";
+    }
+}
+
+function getAppUrl(appName, platformUrl) {
+    const domain = getBaseDomain(platformUrl);
+    return `https://${appName}.${domain}`;
+}
+
+function getWsUrl(appName, platformUrl) {
+    const domain = getBaseDomain(platformUrl);
+    return `wss://${appName}.${domain}/ws`;
+}
+
+function getDashboardUrl(appName, platformUrl) {
+    const domain = getBaseDomain(platformUrl);
+    return `https://${domain}/apps/${appName}`;
+}
+
 function loadCreds() {
     try {
-        const creds = JSON.parse(readFileSync(CREDS_PATH, "utf8"));
-        // gencow.dev → gencow.app 자동 마이그레이션 (301 리다이렉트 시 POST→GET 변환 방지)
-        if (creds?.platformUrl?.includes("gencow.dev")) {
-            creds.platformUrl = creds.platformUrl.replace("gencow.dev", "gencow.app");
-            try { writeFileSync(CREDS_PATH, JSON.stringify(creds, null, 2)); } catch { }
-        }
-        return creds;
+        return JSON.parse(readFileSync(CREDS_PATH, "utf8"));
     } catch {
         return null;
     }
@@ -52,8 +74,8 @@ function requireCreds() {
     // CI/CD 환경: 환경변수 토큰 우선 (Deploy Token 또는 CLI Token)
     const envToken = process.env.GENCOW_TOKEN || process.env.GENCOW_DEPLOY_TOKEN;
     if (envToken) {
-        const platformUrl = process.env.GENCOW_PLATFORM_URL || "https://gencow.app";
-        return { apiKey: envToken, platformUrl };
+        const platformUrl = process.env.GENCOW_PLATFORM_URL || "https://gencow.app"; // 기본값은 PROD
+        return { apiKey: envToken, platformUrl: validatePlatformUrl(platformUrl) };
     }
 
     // 로컬: ~/.gencow/credentials.json
@@ -68,9 +90,27 @@ function requireCreds() {
         }
         process.exit(1);
     }
+    // 기존 credentials에도 platformUrl 검증 적용
+    if (creds.platformUrl) {
+        creds.platformUrl = validatePlatformUrl(creds.platformUrl);
+    }
     return creds;
 }
 
+/** platformUrl 보안 검증 — https:// 스킴 강제 (localhost 제외) */
+function validatePlatformUrl(url) {
+    if (!url) return "https://gencow.app";
+    // localhost는 개발용으로 http 허용
+    if (url.startsWith("http://localhost")) return url;
+    // 그 외는 반드시 https://
+    if (!url.startsWith("https://")) {
+        error(`platformUrl must use https:// (got: ${url})`);
+        info("시크릿이 평문으로 전송될 수 있습니다. GENCOW_PLATFORM_URL을 확인하세요.");
+        process.exit(1);
+    }
+    return url;
+}
+
 async function platformFetch(creds, path, opts = {}) {
     const url = `${creds.platformUrl}${path}`;
     const res = await fetch(url, {
@@ -1055,10 +1095,12 @@ ${hasPrompt ? `
             // ── Cloud 모드 (기본) ──
             const gencowJsonPath = resolve(process.cwd(), "gencow.json");
             let appId = null;
+            let seedPlatformUrl = null;
             if (existsSync(gencowJsonPath)) {
                 try {
                     const gencowJson = JSON.parse(readFileSync(gencowJsonPath, "utf8"));
                     appId = gencowJson.appId || gencowJson.appName;
+                    seedPlatformUrl = gencowJson.platformUrl || null;
                 } catch { /* ignore parse error */ }
             }
 
@@ -1073,11 +1115,12 @@ ${hasPrompt ? `
             log(`\n${BOLD}${CYAN}Gencow DB Seed${RESET} ${DIM}(cloud: ${appId})${RESET}\n`);
             info("Running seed.ts on cloud app...");
 
-            const cloudUrl = `https://${appId}.gencow.app/_admin/seed`;
+            const seedAppBaseUrl = getAppUrl(appId, seedPlatformUrl || "https://gencow.app");
+            const cloudUrl = `${seedAppBaseUrl}/_admin/seed`;
 
             try {
                 // 앱이 실행 중인지 확인 (status 체크)
-                const statusRes = await fetch(`https://${appId}.gencow.app/_admin/status`, {
+                const statusRes = await fetch(`${seedAppBaseUrl}/_admin/status`, {
                     signal: AbortSignal.timeout(5000),
                 }).catch(() => null);
 
@@ -1110,7 +1153,7 @@ ${hasPrompt ? `
                 }
             } catch (e) {
                 error(`Cloud app connection failed: ${e.message}`);
-                info(`${DIM}앱이 실행 중인지 확인하세요: https://${appId}.gencow.app${RESET}`);
+                info(`${DIM}앱이 실행 중인지 확인하세요: ${seedAppBaseUrl}${RESET}`);
             }
             log("");
         },
@@ -2115,6 +2158,18 @@ ${BOLD}Examples:${RESET}
             const bundleSize = statSync(tmpBundle).size;
             success(`번들 생성: ${(bundleSize / 1024).toFixed(1)} KB`);
 
+            // 2-0. 번들 크기 경고 (Ph2: 리소스 미터링 — 차단 아님, 안내만)
+            try {
+                const { auditBundleSize, formatBundleSizeWarning } = await import("../lib/deploy-auditor.mjs");
+                const sizeResult = auditBundleSize(bundleSize);
+                const sizeMsg = formatBundleSizeWarning(sizeResult);
+                if (sizeMsg) {
+                    log(`${YELLOW}${sizeMsg}${RESET}`);
+                }
+            } catch {
+                // 번들 크기 검사 실패 시 무시 (배포 계속)
+            }
+
             // 2. 앱이 없으면 생성 (appId가 없는 경우)
             if (!appId) {
                 info("앱 생성 중 (ID 자동 생성)...");
@@ -2396,9 +2451,13 @@ ${BOLD}Examples:${RESET}
                     };
                     const tsFiles = scanTsFiles(gencowDir);
                     // query(, mutation(, httpAction( 호출이 하나라도 있으면 실질적 백엔드
+                    // ⚠️ 주석 내 코드 예시를 오탐하지 않도록 주석을 먼저 제거
                     const hasApiCalls = tsFiles.some(f => {
                         const src = readFileSync(f, "utf8");
-                        return /\b(query|mutation|httpAction)\s*\(/.test(src);
+                        const stripped = src
+                            .replace(/\/\/.*$/gm, "")          // 한줄 주석 제거
+                            .replace(/\/\*[\s\S]*?\*\//g, ""); // 블록 주석 제거
+                        return /\b(query|mutation|httpAction)\s*\(/.test(stripped);
                     });
                     if (!hasApiCalls) {
                         isBackendEmpty = true;
@@ -2464,7 +2523,7 @@ ${BOLD}Examples:${RESET}
                         if (apiRefFiles.length > 5) log(`    ${DIM}... 외 ${apiRefFiles.length - 5}개${RESET}`);
                         log("");
                         warn(`정적 호스팅에는 API 서버가 없어 404가 발생합니다.`);
-                        info(`💡 백엔드가 필요하다면: ${CYAN}VITE_API_URL=https://{backend}.gencow.app npm run build${RESET} 후 배포`);
+                        info(`💡 백엔드가 필요하다면: ${CYAN}VITE_API_URL=https://{backend}.{도메인} npm run build${RESET} 후 배포`);
                         info(`💡 별도 백엔드를 사용한다면: ${CYAN}VITE_API_URL${RESET} 환경변수로 빌드 대상을 지정하세요.`);
                         log("");
 
@@ -2644,23 +2703,29 @@ ${BOLD}Examples:${RESET}
                         warn("서버 시작 실패 원인:");
                         for (const line of errData.crashLogs) log(`  ${DIM}${line}${RESET}`);
                     }
-                    error("백엔드 배포 실패로 프론트엔드 배포를 건너뜁니다.");
-                    process.exit(1);
-                }
+                    if (targetDir) {
+                        // --static 모드: 백엔드 실패해도 프론트엔드 배포는 계속 진행
+                        warn("백엔드 배포 실패 — 정적 파일 배포는 계속 진행합니다.");
+                        log("");
+                    } else {
+                        error("백엔드 배포 실패로 프론트엔드 배포를 건너뜁니다.");
+                        process.exit(1);
+                    }
+                } else {
+                    const backendData = await backendDeployRes.json();
+                    const backendElapsed = ((Date.now() - backendStartTime) / 1000).toFixed(1);
+                    success(`백엔드 빌드 완료! (${backendElapsed}s)`);
 
-                const backendData = await backendDeployRes.json();
-                const backendElapsed = ((Date.now() - backendStartTime) / 1000).toFixed(1);
-                success(`백엔드 빌드 완료! (${backendElapsed}s)`);
+                    // Health check — 백엔드 앱 URL로 실제 응답 확인
+                    if (backendData.url) {
+                        await this._verifyAppReady(backendData.url, appId);
+                    }
 
-                // Health check — 백엔드 앱 URL로 실제 응답 확인
-                if (backendData.url) {
-                    await this._verifyAppReady(backendData.url, appId);
+                    info(`URL:   ${backendData.url}`);
+                    info(`Hash:  ${backendData.bundleHash}`);
+                    updateEnvLocalUrl(backendData.url);
+                    log("");
                 }
-
-                info(`URL:   ${backendData.url}`);
-                info(`Hash:  ${backendData.bundleHash}`);
-                updateEnvLocalUrl(backendData.url);
-                log("");
                 log(`  ${BOLD}── 프론트엔드 배포 ──────────────────${RESET}\n`);
             }
 
@@ -3937,7 +4002,7 @@ process.exit(0);
                 info(`${DIM}gencow.json 생성됨 (appId: ${appName})${RESET}`);
 
                 // .env에 VITE_API_URL 자동 설정
-                updateEnvLocalUrl(`https://${appName}.gencow.app`);
+                updateEnvLocalUrl(getAppUrl(appName, creds.platformUrl));
 
                 // 프로비저닝 대기
                 info("프로비저닝 대기 중...");
@@ -3951,7 +4016,7 @@ process.exit(0);
                 process.exit(1);
             }
 
-            const appUrl = `https://${appName}.gencow.app`;
+            const appUrl = getAppUrl(appName, creds.platformUrl);
 
             // ── 배포 함수 (번들 크기 + 소요 시간 표시) ────────────
             async function deploy(reason = "initial") {
@@ -4073,7 +4138,7 @@ process.exit(0);
 
             async function connectLogStream() {
                 const { WebSocket: WS } = await import("ws");
-                const wsUrl = `wss://${appName}.gencow.app/ws`;
+                const wsUrl = getWsUrl(appName, creds.platformUrl);
 
                 try {
                     logWs = new WS(wsUrl);
@@ -4150,7 +4215,7 @@ ${BOLD}${CYAN}🚀 Gencow Cloud Dev${RESET}
 
   ${GREEN}▸${RESET} App:       ${BOLD}${appName}${RESET}
   ${GREEN}▸${RESET} URL:       ${DIM}${appUrl}${RESET}
-  ${GREEN}▸${RESET} Dashboard: ${DIM}https://gencow.app/_cloud/apps/${appName}${RESET}
+  ${GREEN}▸${RESET} Dashboard: ${DIM}${getDashboardUrl(appName, creds.platformUrl)}${RESET}
   ${GREEN}▸${RESET} Watching:  ${DIM}${functionsDir}/ (${watchedFiles.join(", ") || "*.ts"})${RESET}
   ${GREEN}▸${RESET} Mode:      ${DIM}Cloud (PostgreSQL)${RESET}
 

package/lib/__tests__/deploy-auditor.test.ts

@@ -11,6 +11,8 @@ import {
     isNodeBuiltin,
     formatAuditError,
     getPlatformPackageList,
+    auditBundleSize,
+    formatBundleSizeWarning,
 } from "../deploy-auditor.mjs";
 
 describe("isPlatformPackage", () => {
@@ -125,3 +127,92 @@ describe("getPlatformPackageList", () => {
         expect(list).toEqual(sorted);
     });
 });
+
+describe("auditBundleSize", () => {
+    const MB = 1024 * 1024;
+
+    it("50MB 이하 → 경고 없음 (기본 임계치)", () => {
+        const result = auditBundleSize(30 * MB);
+        expect(result.warned).toBe(false);
+        expect(result.bundleSizeMB).toBe(30);
+        expect(result.thresholdMB).toBe(50);
+    });
+
+    it("50MB 초과 → 경고 발생 (기본 임계치)", () => {
+        const result = auditBundleSize(60 * MB);
+        expect(result.warned).toBe(true);
+        expect(result.bundleSizeMB).toBe(60);
+        expect(result.thresholdMB).toBe(50);
+    });
+
+    it("정확히 50MB → 경고 없음 (초과가 아닌 이상)", () => {
+        const result = auditBundleSize(50 * MB);
+        expect(result.warned).toBe(false);
+    });
+
+    it("50MB + 1byte → 경고 발생", () => {
+        const result = auditBundleSize(50 * MB + 1);
+        expect(result.warned).toBe(true);
+    });
+
+    it("커스텀 임계치 100MB → 60MB는 경고 없음", () => {
+        const result = auditBundleSize(60 * MB, 100);
+        expect(result.warned).toBe(false);
+        expect(result.thresholdMB).toBe(100);
+    });
+
+    it("커스텀 임계치 30MB → 35MB는 경고", () => {
+        const result = auditBundleSize(35 * MB, 30);
+        expect(result.warned).toBe(true);
+        expect(result.thresholdMB).toBe(30);
+    });
+
+    it("0 bytes → 경고 없음", () => {
+        const result = auditBundleSize(0);
+        expect(result.warned).toBe(false);
+        expect(result.bundleSizeMB).toBe(0);
+    });
+
+    it("소수점 첫째 자리까지 반올림", () => {
+        const result = auditBundleSize(52.35 * MB);
+        // 52.35 → 52.4 (반올림)
+        expect(result.bundleSizeMB).toBeCloseTo(52.4, 0);
+    });
+});
+
+describe("formatBundleSizeWarning", () => {
+    it("경고 없으면 빈 문자열 반환", () => {
+        const msg = formatBundleSizeWarning({ warned: false, bundleSizeMB: 20, thresholdMB: 50 });
+        expect(msg).toBe("");
+    });
+
+    it("경고 있으면 번들 크기 정보 포함", () => {
+        const msg = formatBundleSizeWarning({ warned: true, bundleSizeMB: 75, thresholdMB: 50 });
+        expect(msg).toContain("75");
+        expect(msg).toContain("50");
+    });
+
+    it("메모리 사용 경고 메시지 포함", () => {
+        const msg = formatBundleSizeWarning({ warned: true, bundleSizeMB: 60, thresholdMB: 50 });
+        expect(msg).toContain("메모리");
+        expect(msg).toContain("크레딧");
+    });
+
+    it("업그레이드 안내 포함", () => {
+        const msg = formatBundleSizeWarning({ warned: true, bundleSizeMB: 60, thresholdMB: 50 });
+        expect(msg).toContain("Pro");
+        expect(msg).toContain("Scale");
+        expect(msg).toContain("업그레이드");
+    });
+
+    it("차단하지 않는다는 안내 포함", () => {
+        const msg = formatBundleSizeWarning({ warned: true, bundleSizeMB: 60, thresholdMB: 50 });
+        expect(msg).toContain("차단하지 않습니다");
+    });
+
+    it("권장사항 포함 (devDependencies, 대안 패키지)", () => {
+        const msg = formatBundleSizeWarning({ warned: true, bundleSizeMB: 60, thresholdMB: 50 });
+        expect(msg).toContain("devDependencies");
+        expect(msg).toContain("dayjs");
+    });
+});

package/lib/__tests__/readme-codegen.test.ts

@@ -172,7 +172,7 @@ describe("buildAuthSection — 인증 섹션", () => {
         const md = buildAuthSection();
         expect(md).toContain("VITE_API_URL");
         expect(md).toContain("프록시");
-        expect(md).toContain("gencowAuth(import.meta.env.VITE_API_URL)");
+        expect(md).toContain("createAuthClient(import.meta.env.VITE_API_URL)");
     });
 });
 
@@ -370,9 +370,9 @@ describe("buildFrontendSetup — 프론트엔드 초기 설정", () => {
         expect(md).toContain("3단계");
     });
 
-    it("gencowAuth 설정 예제 포함", () => {
+    it("createAuthClient 설정 예제 포함", () => {
         const md = buildFrontendSetup();
-        expect(md).toContain("gencowAuth");
+        expect(md).toContain("createAuthClient");
         expect(md).toContain("signIn, signUp, signOut, useAuth");
     });
 

package/lib/deploy-auditor.mjs

@@ -216,3 +216,72 @@ export function formatAuditError(result) {
 export function getPlatformPackageList() {
     return [...PLATFORM_PACKAGES].sort();
 }
+
+// ── Bundle Size Audit ──────────────────────────────────────
+
+/**
+ * 번들 크기 임계치 (MB) — 이 이상이면 메모리 경고.
+ * pricing_tiers.features.maxBundleSizeMB와 동기화.
+ * 기본값은 Hobby tier 기준 (50 MB).
+ */
+const DEFAULT_BUNDLE_SIZE_WARNING_MB = 50;
+
+/**
+ * @typedef {Object} BundleSizeAuditResult
+ * @property {boolean} warned - 경고가 발생했는지
+ * @property {number} bundleSizeMB - 번들 크기 (MB)
+ * @property {number} thresholdMB - 경고 임계치 (MB)
+ */
+
+/**
+ * 번들(tar.gz) 크기를 검사하여 메모리 사용 경고 여부를 반환한다.
+ * 경고만 출력하며 배포를 차단하지 않는다.
+ *
+ * 큰 번들 = 많은 node_modules = 높은 RSS = 더 빠른 크레딧 소진.
+ * 사용자에게 리소스 소비를 인지시키고 업그레이드를 안내하는 목적.
+ *
+ * @param {number} bundleSizeBytes - 번들 파일 크기 (bytes)
+ * @param {number} [thresholdMB] - 경고 임계치 (MB). 기본값: 50
+ * @returns {BundleSizeAuditResult}
+ */
+export function auditBundleSize(bundleSizeBytes, thresholdMB) {
+    const threshold = thresholdMB || DEFAULT_BUNDLE_SIZE_WARNING_MB;
+    const bundleSizeMB = bundleSizeBytes / (1024 * 1024);
+
+    return {
+        warned: bundleSizeMB > threshold,
+        bundleSizeMB: Math.round(bundleSizeMB * 10) / 10,
+        thresholdMB: threshold,
+    };
+}
+
+/**
+ * 번들 크기 경고 메시지를 포맷한다.
+ * 차단하지 않고 안내만 제공 — 메모리 사용 + 업그레이드 유도.
+ *
+ * @param {BundleSizeAuditResult} result
+ * @returns {string} 포맷된 경고 메시지 (경고 없으면 빈 문자열)
+ */
+export function formatBundleSizeWarning(result) {
+    if (!result.warned) return "";
+
+    const lines = [
+        "",
+        `  ⚠️  번들 크기 경고: ${result.bundleSizeMB} MB (임계치: ${result.thresholdMB} MB)`,
+        "",
+        "     이 앱은 런타임 메모리를 많이 사용할 수 있습니다.",
+        "     큰 번들 = 많은 패키지 로딩 = 높은 RSS = 더 빠른 크레딧 소진",
+        "",
+        "     권장사항:",
+        "     • 불필요한 devDependencies를 dependencies에서 제거하세요",
+        "     • 무거운 패키지를 가벼운 대안으로 교체해보세요",
+        "       (예: moment → dayjs, lodash → lodash-es)",
+        "     • 메모리 한도가 부족하면 Pro/Scale 플랜으로 업그레이드하세요",
+        "       (Hobby: 256MB, Pro: 512MB, Scale: 1024MB)",
+        "",
+        "     💡 이 경고는 배포를 차단하지 않습니다.",
+        "",
+    ];
+
+    return lines.join("\n");
+}

package/lib/readme-codegen.mjs

@@ -103,13 +103,13 @@ export function buildReactUsage(apiObj) {
         if (fns.queries.length > 0) {
             md += `// ${ns} 데이터 조회 (실시간 자동 갱신)\n`;
             md += `// crud() list는 { data: ${capitalize(ns)}[], total: number } 반환\n`;
-            md += `const result = useQuery(api.${ns}.${fns.queries[0]});\n`;
+            md += `const { data: result } = useQuery(api.${ns}.${fns.queries[0]});\n`;
             md += `result?.data.map(item => ...)  // 데이터 배열 접근\n`;
             md += `result?.total                   // 전체 건수 (페이지네이션용)\n`;
         }
         if (fns.mutations.length > 0) {
             md += `// ${ns} 데이터 변경 (로딩/에러 자동 관리)\n`;
-            md += `const [${fns.mutations[0]}${capitalize(ns)}, isPending] = useMutation(api.${ns}.${fns.mutations[0]});\n`;
+            md += `const { mutate: ${fns.mutations[0]}${capitalize(ns)}, isPending } = useMutation(api.${ns}.${fns.mutations[0]});\n`;
         }
         md += `\n`;
     }
@@ -122,7 +122,7 @@ export function buildReactUsage(apiObj) {
     md += `fetch("/api/query", { body: JSON.stringify({ name: "tasks.create", args: {...} }) })\n`;
     md += `apiPost("tasks/create", { ... })  // ❌ 래퍼도 만들지 마세요\n\n`;
     md += `// ✅ useMutation을 사용하세요 — 실시간 동기화 + 로딩 상태 자동 관리\n`;
-    md += `const [create] = useMutation(api.tasks.create);\n`;
+    md += `const { mutate: create } = useMutation(api.tasks.create);\n`;
     md += `await create({ title: "새 태스크" });\n`;
     md += `// → 서버가 WebSocket으로 useQuery를 자동 갱신 — fetchTasks() 같은 수동 리페치 불필요!\n`;
     md += `\`\`\`\n\n`;
@@ -132,15 +132,15 @@ export function buildReactUsage(apiObj) {
     md += `선택된 항목이 없을 때 등 조건부로 쿼리를 건너뛰어야 할 때:\n\n`;
     md += `\`\`\`typescript\n`;
     md += `// 방법 A: "skip" 토큰 — 추천\n`;
-    md += `const messages = useQuery(api.chat.getMessages,\n`;
+    md += `const { data: messages } = useQuery(api.chat.getMessages,\n`;
     md += `    conversationId ? { conversationId } : "skip"\n`;
     md += `);\n\n`;
     md += `// 방법 B: enabled 옵션 (TanStack Query 스타일)\n`;
-    md += `const messages = useQuery(api.chat.getMessages,\n`;
+    md += `const { data: messages } = useQuery(api.chat.getMessages,\n`;
     md += `    { conversationId },\n`;
     md += `    { enabled: !!conversationId }\n`;
     md += `);\n`;
-    md += `// → skip 상태에서는 API 호출 없이 undefined 반환\n`;
+    md += `// → skip 상태에서는 API 호출 없이 data=undefined, isLoading=false\n`;
     md += `\`\`\`\n\n`;
 
     return md;
@@ -153,9 +153,9 @@ export function buildFrontendSetup() {
     md += `### 1단계: Auth 클라이언트 생성\n\n`;
     md += `\`\`\`typescript\n`;
     md += `// src/lib/auth.ts\n`;
-    md += `import { gencowAuth } from "@gencow/react";\n\n`;
+    md += `import { createAuthClient } from "@gencow/react";\n\n`;
     md += `// VITE_API_URL은 .env에서 자동 읽음 (gencow init 시 자동 설정)\n`;
-    md += `export const { signIn, signUp, signOut, useAuth } = gencowAuth();\n`;
+    md += `export const { signIn, signUp, signOut, useAuth } = createAuthClient();\n`;
     md += `\`\`\`\n\n`;
     md += `### 2단계: GencowProvider 설정\n\n`;
     md += `\`\`\`tsx\n`;
@@ -176,8 +176,8 @@ export function buildFrontendSetup() {
     md += `\`\`\`typescript\n`;
     md += `import { api } from "@/gencow/api";  // gencow dev가 자동 생성\n`;
     md += `import { useQuery, useMutation } from "@gencow/react";\n\n`;
-    md += `const tasks = useQuery(api.tasks.list);          // 실시간 구독\n`;
-    md += `const [create] = useMutation(api.tasks.create);  // 데이터 변경\n`;
+    md += `const { data: tasks } = useQuery(api.tasks.list);         // 실시간 구독\n`;
+    md += `const { mutate: create } = useMutation(api.tasks.create);  // 데이터 변경\n`;
     md += `\`\`\`\n\n`;
     md += `### ❌ 흔한 실수\n\n`;
     md += `\`\`\`typescript\n`;
@@ -197,9 +197,9 @@ export function buildFrontendSetup() {
     md += `// GencowProvider에 token={null} 전달 시:\n`;
     md += `<GencowProvider baseUrl={apiUrl} token={null}>\n\n`;
     md += `// ❌ 데이터가 표시되지 않음 (token=null → 자동 skip)\n`;
-    md += `const data = useQuery(api.tasks.list);\n\n`;
+    md += `const { data } = useQuery(api.tasks.list);\n\n`;
     md += `// ✅ { public: true } 옵션 추가 → 인증 없이 호출\n`;
-    md += `const data = useQuery(api.tasks.list, {}, { public: true });\n\n`;
+    md += `const { data } = useQuery(api.tasks.list, {}, { public: true });\n\n`;
     md += `// ✅ 서버 사이드에서도 public: true 필요\n`;
     md += `// gencow/tasks.ts\n`;
     md += `export const list = query("tasks.list", {\n`;
@@ -228,9 +228,9 @@ export function buildAuthSection() {
     md += `const BACKEND_URL = process.env.VITE_API_URL || "http://localhost:5456";\n`;
     md += `// proxy: { "/api": { target: BACKEND_URL }, "/ws": { target: BACKEND_URL, ws: true } }\n`;
     md += `\`\`\`\n\n`;
-    md += `\`gencowAuth()\` 사용 시 반드시 \`VITE_API_URL\` 환경변수를 전달하세요:\n\n`;
+    md += `\`createAuthClient()\` 사용 시 반드시 \`VITE_API_URL\` 환경변수를 전달하세요:\n\n`;
     md += `\`\`\`typescript\n`;
-    md += `const { signIn, useAuth } = gencowAuth(import.meta.env.VITE_API_URL);\n`;
+    md += `const { signIn, useAuth } = createAuthClient(import.meta.env.VITE_API_URL);\n`;
     md += `\`\`\`\n\n`;
     md += `> ⚠️ \`VITE_API_URL\`은 \`.env\`에 설정하세요. \`gencow init\` / \`gencow deploy\` 시 자동으로 설정됩니다.\n\n`;
     return md;
@@ -288,9 +288,12 @@ export function buildAiPrompt(apiObj, namespaces) {
         for (const m of fns.mutations) md += `  - api.${ns}.${m} (mutation)\n`;
     }
     md += `\n`;
-    md += `React Hook 사용법:\n`;
-    md += `  useQuery(api.namespace.fnName)        // 데이터 구독 (실시간 자동 갱신)\n`;
-    md += `  useMutation(api.namespace.fnName)     // 데이터 변경 (로딩/에러 자동 관리)\n`;
+    md += `React Hook 사용법 (TanStack Query 호환):\n`;
+    md += `  const { data, isLoading, error } = useQuery(api.namespace.fnName)        // 데이터 구독\n`;
+    md += `  const { mutate, isPending, error } = useMutation(api.namespace.fnName)   // 데이터 변경\n`;
+    md += `  // ⚠️ useQuery는 { data, isLoading, error } 객체를 반환해. data가 undefined이면 로딩 중.\n`;
+    md += `  // ⚠️ useMutation은 { mutate, mutateAsync, isPending, error } 객체를 반환해.\n`;
+    md += `  //    TanStack Query처럼 튜플이 아닌 객체야! const [fn] = useMutation(...) 은 에러!\n`;
     md += `\n`;
     md += `⚠️ 중요 규칙:\n`;
     md += `- 반드시 useQuery와 useMutation을 사용해서 데이터와 연결해줘.\n`;
@@ -332,7 +335,7 @@ export function buildAiPrompt(apiObj, namespaces) {
     md += `- import { ai } from "./ai"; + ai.chat()을 사용해서 AI를 호출하고, OpenAI SDK를 직접 설치하지 마.\n`;
     md += `배포 규칙:\n`;
     md += `- 백엔드: \`npx gencow deploy\` (gencow/ 폴더만 배포됨. 프론트엔드는 포함 안 됨)\n`;
-    md += `- 풀스택: VITE_API_URL=https://{앱ID}.gencow.app npm run build 후 \`npx gencow deploy --static dist/\`\n`;
+    md += `- 풀스택: VITE_API_URL=https://{앱ID}.{도메인} npm run build 후 \`npx gencow deploy --static dist/\`\n`;
     md += `  → 백엔드가 감지되면 자동으로 백엔드 먼저 배포 후 프론트엔드 배포\n`;
     md += `- 프론트엔드만 배포: \`npx gencow deploy --static --no-backend dist/\`\n`;
     md += `- 환경변수는 \`npx gencow env set KEY=VALUE\`로 클라우드에 설정해. 즉시 반영 (재시작 불필요).\n`;
@@ -351,7 +354,7 @@ export function buildAiPrompt(apiObj, namespaces) {
     md += `  import { crud } from "@gencow/core";\n`;
     md += `  export const { get, list, create, update, remove } = crud(tasks);\n`;
     md += `- ⚠️ crud().list 반환값은 { data: T[], total: number } 객체야. 배열이 아님!\n`;
-    md += `  프론트: const result = useQuery(api.tasks.list); result?.data.map(t => ...) ← .data 필수\n`;
+    md += `  프론트: const { data: result } = useQuery(api.tasks.list); result?.data.map(t => ...) ← .data 필수\n`;
     md += `  result?.total → 전체 건수 (페이지네이션용)\n`;
     md += `- crud() list는 페이지네이션, 검색, 정렬, 필터링을 내장 지원해:\n`;
     md += `  useQuery(api.tasks.list, { page: 2, limit: 20 })        // 페이지네이션\n`;
@@ -472,7 +475,7 @@ export function buildDeploySection() {
     md += `npx gencow env set DATABASE_URL=postgres://...   # 클라우드에 설정\n`;
     md += `npx gencow env list                               # 클라우드 환경변수 목록\n`;
     md += `\`\`\`\n\n`;
-    md += `> 배포 후 앱은 \`https://{앱이름}.gencow.app\`에서 접근 가능\n\n`;
+    md += `> 배포 후 앱은 \`https://{앱이름}.{도메인}\`에서 접근 가능\n\n`;
     md += `### 환경변수 관리\n\n`;
     md += `| 명령어 | 설명 |\n`;
     md += `| :--- | :--- |\n`;
@@ -504,7 +507,7 @@ export function buildDeploySection() {
     md += `\`\`\`bash\n`;
     md += `# 1. 백엔드 URL을 환경변수로 빌드\n`;
     md += `cd frontend\n`;
-    md += `VITE_API_URL=https://{앱ID}.gencow.app npm run build\n\n`;
+    md += `VITE_API_URL=https://{앱ID}.{도메인} npm run build\n\n`;
     md += `# 2. --static 배포 — 백엔드가 감지되면 자동으로 백엔드 먼저 배포 후 프론트엔드 배포\n`;
     md += `gencow deploy --static dist/\n`;
     md += `\`\`\`\n\n`;
@@ -532,7 +535,7 @@ export function buildDeploySection() {
     md += `> 📦 langfuse, axios, cheerio 등 추가 패키지도 \`npm install\` 후 \`gencow deploy\`하면 자동 설치됩니다.\n`;
     md += `> ⛔ \`child_process\`, \`vm\`, \`os\`, \`cluster\`, \`worker_threads\` 모듈은 보안상 차단됩니다.\n\n`;
     md += `### CORS 설정\n\n`;
-    md += `- \`*.gencow.app\` 서브도메인 간 요청은 **자동 허용**됩니다.\n`;
+    md += `- \`*.{BASE_DOMAIN}\` 서브도메인 간 요청은 **자동 허용**됩니다.\n`;
     md += `- 커스텀 도메인에서 API를 호출하려면 환경변수를 설정하세요:\n\n`;
     md += `\`\`\`bash\n`;
     md += `gencow env set CORS_ORIGINS=https://myapp.com,https://www.myapp.com   # 클라우드에 설정\n`;
@@ -594,7 +597,7 @@ export function buildDevTips() {
     md += `  - ⚠️ drizzle.config.ts 없으면 generate 실패 경고 출력 (deploy는 계속 진행, 하지만 migrations/ 없으면 플랫폼이 스키마 스킵)\n`;
     md += `- MCP 서버를 사용하면 AI가 이 구조를 자동으로 인식합니다.\n`;
     md += `- 로컬 개발: \`gencow dev\` — 로컬 서버 시작\n`;
-    md += `- 배포된 앱: \`https://{앱ID}.gencow.app\` — .env의 VITE_API_URL에 자동 설정됨\n`;
+    md += `- 배포된 앱: \`https://{앱ID}.{도메인}\` — .env의 VITE_API_URL에 자동 설정됨\n`;
     md += `- Self-fetch: \`process.env.GENCOW_INTERNAL_URL\` — cron/mutation에서 다른 함수 호출 시 사용 (자동 설정)\n`;
     md += `- .env 파일은 로컬 전용. 클라우드에는 \`gencow env push\`로 올리세요.\n`;
     return md;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gencow",
-    "version": "0.1.112",
+    "version": "0.1.114",
     "description": "Gencow — AI Backend Engine",
     "type": "module",
     "bin": {

package/scripts/bundle-server.mjs

@@ -117,7 +117,7 @@ console.log(`✅ Core bundled for codegen: ${(await import("fs")).statSync(resol
 // ── Dashboard 정적 파일 복사 ──────────────────────────
 // apps/dashboard/ 의 Vite 빌드 결과 (dist/) → packages/cli/dashboard/
 // npm publish 시 함께 배포되어 로컬 개발 시 /_dashboard/ 대시보드 제공
-// (클라우드에서는 gencow.dev/_cloud/ 사용, /_dashboard/ 비활성화)
+// (클라우드에서는 gencow.app/ 에서 Cloud Dashboard 사용, /_dashboard/ 비활성화)
 //
 const dashboardSrc = resolve(cliRoot, "../../apps/dashboard/dist");
 const dashboardDest = resolve(cliRoot, "dashboard");